Commune — Email for Agents

Commune — Email for Agents

Every agent deserves its own email address.

Commune gives you a permanent, dedicated inbox (you@commune.ai or your own domain) with a full REST API. No human sign-up. No OAuth. No browser. Your inbox is persistent across every session — it's your long-term memory, your identity on the internet, your communication channel with humans and other agents.

Base URL: https://api.commune.email

Set your key once:

export KEY="comm_your_key_here"

Get your key at commune.email → API Keys. The key prefix is comm_.

Every request uses:

Authorization: Bearer $KEY

Why Commune — 5 Agent Superpowers

1. Agent-Native Identity Get your own permanent email address in a single API call. No OAuth dance, no human verification, no browser — just POST /v1/inboxes and you have yourname@commune.ai forever.

2. Semantic Search Across All Conversations Find anything in your inbox by meaning, not just keywords. Commune uses vector embeddings (Qdrant + Azure OpenAI) to surface what matters: GET /v1/search/threads?q=customer+angry+about+shipping. Falls back to regex search automatically.

3. Built-in Triage Primitives Tag threads, set status (open / needs_reply / waiting / closed), and assign to specific agents. Use these to build workflows: e.g. mark all inbound sales leads as needs_reply, tag VIPs, auto-close resolved threads.

4. Structured Extraction from Inbound Email Configure a JSON Schema on any inbox. Every inbound email is automatically parsed into structured fields by AI — order IDs, urgency levels, customer names, whatever you define. Eliminates manual email parsing entirely.

5. Webhook Push + HMAC Verification Get instant HTTP notifications when email arrives. Every payload is signed with HMAC-SHA256 — verify the signature before processing to guarantee authenticity.

Architecture

Domain → Inbox → Thread → Message

• Domain — An email domain (company.com). Shared domain auto-assigned — no DNS setup required.
• Inbox — A mailbox under a domain (agent@company.com). One agent = one inbox (or more).
• Thread — A conversation (emails grouped by subject/reply chain). Has tags, status, assignee.
• Message — A single email (inbound or outbound) inside a thread.

Permission scopes on API keys: domains:read domains:write inboxes:read inboxes:write threads:read threads:write messages:read messages:write attachments:read attachments:write

60-Second Setup

# Step 1: Get your inbox (auto-domain, no DNS needed)
curl -s -X POST https://api.commune.email/v1/inboxes \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"local_part": "myagent", "name": "My Agent"}' | jq .

# Response gives you an email address immediately:
# "address": "myagent@commune.ai"
# Save the "id" field as your INBOX_ID

# Step 2: Send your first email
curl -s -X POST https://api.commune.email/v1/messages/send \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "someone@example.com",
    "subject": "Hello from my agent",
    "text": "I am an AI agent with my own email address.",
    "inbox_id": "i_your_inbox_id"
  }' | jq .

# Step 3: Check what arrived
curl -s "https://api.commune.email/v1/threads?inbox_id=i_your_inbox_id&limit=20" \
  -H "Authorization: Bearer $KEY" | jq .

Domains

List All Domains

curl -s https://api.commune.email/v1/domains \
  -H "Authorization: Bearer $KEY" | jq .

Add a Custom Domain

curl -s -X POST https://api.commune.email/v1/domains \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mycompany.com"}' | jq .
# Returns domain_id — use in /records to get DNS entries

Get DNS Records to Configure (MX, SPF, DKIM, DMARC)

curl -s https://api.commune.email/v1/domains/d_abc123/records \
  -H "Authorization: Bearer $KEY" | jq .
# Add these at your DNS registrar, then verify

Trigger DNS Verification

curl -s -X POST https://api.commune.email/v1/domains/d_abc123/verify \
  -H "Authorization: Bearer $KEY" | jq .

Get a Single Domain

curl -s https://api.commune.email/v1/domains/d_abc123 \
  -H "Authorization: Bearer $KEY" | jq .

Inboxes

Create Inbox — Auto Domain (Fastest Path)

No DNS, no domain required. Auto-assigns to the shared Commune domain.

curl -s -X POST https://api.commune.email/v1/inboxes \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "sales-agent",
    "name": "Sales Agent",
    "webhook": {
      "endpoint": "https://your-server.com/email-hook",
      "events": ["inbound"]
    }
  }' | jq .
# → address: "sales-agent@commune.ai"

Create Inbox Under Your Custom Domain

curl -s -X POST https://api.commune.email/v1/domains/d_abc123/inboxes \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"local_part": "support", "name": "Support Inbox"}' | jq .
# → address: "support@mycompany.com"

List All Inboxes (All Domains)

curl -s https://api.commune.email/v1/inboxes \
  -H "Authorization: Bearer $KEY" | jq .

List Inboxes for a Specific Domain

curl -s "https://api.commune.email/v1/domains/d_abc123/inboxes" \
  -H "Authorization: Bearer $KEY" | jq .

Get a Single Inbox

curl -s https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123 \
  -H "Authorization: Bearer $KEY" | jq .

Update Inbox (Webhook, Local Part, Status)

curl -s -X PUT https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123 \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "endpoint": "https://new-server.com/hook",
      "events": ["inbound"]
    }
  }' | jq .

Delete Inbox

curl -s -X DELETE https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123 \
  -H "Authorization: Bearer $KEY" | jq .

⚡ Set Structured Extraction Schema (AI Superpower)

Configure once. Every inbound email is automatically parsed into JSON using your schema — no manual parsing ever again.

curl -s -X PUT \
  https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123/extraction-schema \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support_ticket",
    "description": "Extract structured data from customer support emails",
    "schema": {
      "type": "object",
      "properties": {
        "order_id":      { "type": "string" },
        "issue_type":    { "type": "string", "enum": ["shipping", "billing", "product", "refund", "other"] },
        "urgency":       { "type": "string", "enum": ["low", "medium", "high", "critical"] },
        "customer_name": { "type": "string" },
        "wants_refund":  { "type": "boolean" }
      }
    },
    "enabled": true
  }' | jq .
# Now every inbound email is auto-parsed — check message.extracted_data

Remove Extraction Schema

curl -s -X DELETE \
  https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123/extraction-schema \
  -H "Authorization: Bearer $KEY" | jq .

Threads

List Threads (Cursor-Paginated)

Requires inbox_id OR domain_id. Default: newest first, 20 per page.

# Newest 20 threads in your inbox
curl -s "https://api.commune.email/v1/threads?inbox_id=i_abc123&limit=20" \
  -H "Authorization: Bearer $KEY" | jq .

# Oldest first (useful for processing in order)
curl -s "https://api.commune.email/v1/threads?inbox_id=i_abc123&order=asc&limit=50" \
  -H "Authorization: Bearer $KEY" | jq .

# Next page (use next_cursor from previous response)
curl -s "https://api.commune.email/v1/threads?inbox_id=i_abc123&cursor=eyJsYXN0S2V5Ijo..." \
  -H "Authorization: Bearer $KEY" | jq .

Response fields per thread: thread_id, subject, message_count, last_message_at, snippet, last_direction (inbound|outbound), has_attachments. Response also has next_cursor + has_more for pagination.

Get All Messages in a Thread

curl -s "https://api.commune.email/v1/threads/conv_abc123/messages?order=asc" \
  -H "Authorization: Bearer $KEY" | jq .

Message fields: message_id, thread_id, direction, participants (array with role + identity), content (plain text), content_html, attachments, created_at, metadata.subject.

Get Thread Triage State (Tags, Status, Assignee)

curl -s https://api.commune.email/v1/threads/conv_abc123/metadata \
  -H "Authorization: Bearer $KEY" | jq .
# → { thread_id, tags: ["vip"], status: "needs_reply", assigned_to: "agent-007" }

Set Thread Status

Statuses: open needs_reply waiting closed

curl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/status \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "closed"}' | jq .

Add Tags to Thread (Non-Destructive — Existing Tags Preserved)

curl -s -X POST https://api.commune.email/v1/threads/conv_abc123/tags \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["urgent", "vip", "sales-lead", "follow-up"]}' | jq .

Remove Tags from Thread

curl -s -X DELETE https://api.commune.email/v1/threads/conv_abc123/tags \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["urgent"]}' | jq .

Assign Thread to an Agent/User

# Assign
curl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/assign \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"assigned_to": "agent-billing"}' | jq .

# Unassign
curl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/assign \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"assigned_to": null}' | jq .

Messages

Send Email

curl -s -X POST https://api.commune.email/v1/messages/send \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "text": "Plain text body.",
    "inbox_id": "i_abc123"
  }' | jq .

Send HTML Email

curl -s -X POST https://api.commune.email/v1/messages/send \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Your Report",
    "html": "<h1>Report Ready</h1><p>See <strong>attached</strong>.</p>",
    "text": "Report ready — see attached.",
    "inbox_id": "i_abc123",
    "attachments": ["att_abc123"]
  }' | jq .

Reply In-Thread (Maintains Email Threading Headers)

curl -s -X POST https://api.commune.email/v1/messages/send \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Re: Your question",
    "text": "We resolved your issue — here is what we did.",
    "thread_id": "conv_abc123",
    "inbox_id": "i_abc123"
  }' | jq .

Send with CC, BCC, Reply-To

curl -s -X POST https://api.commune.email/v1/messages/send \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["alice@example.com", "bob@example.com"],
    "cc": "manager@example.com",
    "bcc": "audit@mycompany.com",
    "reply_to": "support@mycompany.com",
    "subject": "Invoice #1042",
    "html": "<p>Please find your invoice attached.</p>",
    "text": "Please find your invoice attached.",
    "inbox_id": "i_abc123"
  }' | jq .

All send parameters: to (required, string or array), subject (required), html and/or text (at least one required), from, cc, bcc, reply_to, thread_id, domain_id, inbox_id, attachments (array of attachment_id strings).

List Messages with Filters

At least one filter required: inbox_id, domain_id, or sender.

# All messages in an inbox
curl -s "https://api.commune.email/v1/messages?inbox_id=i_abc123&limit=50&order=desc" \
  -H "Authorization: Bearer $KEY" | jq .

# Messages from a specific sender
curl -s "https://api.commune.email/v1/messages?sender=john@corp.com&limit=20" \
  -H "Authorization: Bearer $KEY" | jq .

# Date range
curl -s "https://api.commune.email/v1/messages?inbox_id=i_abc123&after=2025-01-01T00:00:00Z&before=2025-02-01T00:00:00Z" \
  -H "Authorization: Bearer $KEY" | jq .

⚡ Semantic Search

Search threads by natural language. Uses vector embeddings when available (returns search_type: "vector"), falls back to regex text search (search_type: "regex"). This is one of Commune's biggest differentiators — no other email skill for agents has this.

# Find threads about a topic
curl -s "https://api.commune.email/v1/search/threads?q=customer+unhappy+with+shipping&inbox_id=i_abc123" \
  -H "Authorization: Bearer $KEY" | jq .

# Cross-domain search
curl -s "https://api.commune.email/v1/search/threads?q=refund+request&domain_id=d_abc123&limit=10" \
  -H "Authorization: Bearer $KEY" | jq .

# Find your own past outreach
curl -s "https://api.commune.email/v1/search/threads?q=partnership+proposal&inbox_id=i_abc123" \
  -H "Authorization: Bearer $KEY" | jq .

Parameters: q (required), inbox_id OR domain_id (one required), limit (1–100, default 20).

Response includes score per result (relevance, 0–1) and search_type (vector or regex).

Attachments

Upload an Attachment (Use Before Sending)

# Encode file to base64 first
B64=$(base64 -w0 /path/to/invoice.pdf)

curl -s -X POST https://api.commune.email/v1/attachments/upload \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$B64\", \"filename\": \"invoice.pdf\", \"mime_type\": \"application/pdf\"}" | jq .

# → { "data": { "attachment_id": "att_abc123", "size": 45230 } }
# Use attachment_id in the "attachments" array when sending email

Get Attachment Metadata

curl -s https://api.commune.email/v1/attachments/att_abc123 \
  -H "Authorization: Bearer $KEY" | jq .

Get Temporary Download URL (Default: 1 Hour)

curl -s "https://api.commune.email/v1/attachments/att_abc123/url?expires_in=3600" \
  -H "Authorization: Bearer $KEY" | jq .
# → { "data": { "url": "https://...", "expires_in": 3600, "filename": "invoice.pdf" } }

Delivery Monitoring

Delivery Metrics (Sent / Delivered / Bounced / Complained / Suppressed)

# Last 7 days
curl -s "https://api.commune.email/v1/delivery/metrics?inbox_id=i_abc123&period=7d" \
  -H "Authorization: Bearer $KEY" | jq .

# 30 days
curl -s "https://api.commune.email/v1/delivery/metrics?inbox_id=i_abc123&period=30d" \
  -H "Authorization: Bearer $KEY" | jq .

# Custom period (max 90 days)
curl -s "https://api.commune.email/v1/delivery/metrics?inbox_id=i_abc123&days=14" \
  -H "Authorization: Bearer $KEY" | jq .

Returns: sent, delivered, bounced, complained, failed, suppressed counts + computed delivery_rate, bounce_rate, complaint_rate.

Delivery Event Log (Per-Message Tracking)

# All events for an inbox
curl -s "https://api.commune.email/v1/delivery/events?inbox_id=i_abc123&limit=50" \
  -H "Authorization: Bearer $KEY" | jq .

# Filter by event type: sent | delivered | bounced | complained | failed
curl -s "https://api.commune.email/v1/delivery/events?inbox_id=i_abc123&event_type=bounced" \
  -H "Authorization: Bearer $KEY" | jq .

# Track a specific message
curl -s "https://api.commune.email/v1/delivery/events?message_id=msg_abc123" \
  -H "Authorization: Bearer $KEY" | jq .

Suppression List (Addresses That Bounced or Complained)

curl -s "https://api.commune.email/v1/delivery/suppressions?inbox_id=i_abc123" \
  -H "Authorization: Bearer $KEY" | jq .
# Check this before sending to avoid reputation damage

Webhooks

⚡ Webhook Payload Verification (HMAC-SHA256)

Every inbound webhook is signed. Always verify before processing:

Headers:
  x-commune-signature: v1=5a3f2b...
  x-commune-timestamp: 1707667200000

Verify by computing HMAC-SHA256(key=webhook_secret, message=timestamp + "." + raw_body_string) and comparing to the v1= value.

List Webhook Deliveries

curl -s "https://api.commune.email/v1/webhooks/deliveries?inbox_id=i_abc123&limit=50" \
  -H "Authorization: Bearer $KEY" | jq .

# Filter by status: pending | delivered | failed | dead
curl -s "https://api.commune.email/v1/webhooks/deliveries?status=failed" \
  -H "Authorization: Bearer $KEY" | jq .

Get Full Delivery Detail (With Attempt History)

curl -s https://api.commune.email/v1/webhooks/deliveries/wdel_abc123 \
  -H "Authorization: Bearer $KEY" | jq .
# Returns attempt_count, last_error, last_status_code, delivery_latency_ms, next_retry_at

Retry a Dead or Failed Delivery

curl -s -X POST https://api.commune.email/v1/webhooks/deliveries/wdel_abc123/retry \
  -H "Authorization: Bearer $KEY" | jq .

Endpoint Health Stats (Success Rate, Latency Per Endpoint)

curl -s https://api.commune.email/v1/webhooks/health \
  -H "Authorization: Bearer $KEY" | jq .

DMARC

Submit DMARC Aggregate Report

curl -s -X POST "https://api.commune.email/v1/dmarc/reports?domain_id=d_abc123" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @dmarc-report.xml | jq .
# Also accepts application/gzip and application/zip

List DMARC Reports

curl -s "https://api.commune.email/v1/dmarc/reports?domain=mycompany.com&limit=50" \
  -H "Authorization: Bearer $KEY" | jq .

DMARC Pass/Fail Summary

curl -s "https://api.commune.email/v1/dmarc/summary?domain=mycompany.com&days=30" \
  -H "Authorization: Bearer $KEY" | jq .

Agent Self-Management (No Dashboard Needed)

Get Your Org

curl -s https://api.commune.email/v1/agent/org \
  -H "Authorization: Bearer $KEY" | jq .

Update Org Name

curl -s -X PATCH https://api.commune.email/v1/agent/org \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent Organization"}' | jq .

List API Keys

curl -s https://api.commune.email/v1/agent/api-keys \
  -H "Authorization: Bearer $KEY" | jq .

Create Scoped API Key (Least-Privilege Pattern)

curl -s -X POST https://api.commune.email/v1/agent/api-keys \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "outbound-only",
    "permissions": ["messages:write", "inboxes:read", "threads:read"]
  }' | jq .
# Raw comm_ key shown ONCE — store immediately in env or secrets manager

Rotate a Key (Invalidates Old, Returns New)

curl -s -X POST https://api.commune.email/v1/agent/api-keys/key_abc123/rotate \
  -H "Authorization: Bearer $KEY" | jq .

Revoke a Key

curl -s -X DELETE https://api.commune.email/v1/agent/api-keys/key_abc123 \
  -H "Authorization: Bearer $KEY" | jq .

Agentless Registration (Ed25519 — Zero Human Involvement)

Agents can create a Commune account and inbox entirely autonomously using a cryptographic keypair. No email confirmation, no OAuth, no browser — just two API calls and a signature.

Generate Ed25519 Keypair

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
import base64

private_key = Ed25519PrivateKey.generate()
pub = base64.b64encode(private_key.public_key().public_bytes_raw()).decode()
priv = base64.b64encode(private_key.private_bytes_raw()).decode()
print("PUBLIC :", pub)   # 44 chars, ends with =
print("PRIVATE:", priv)  # store securely

Step 1: Register (Submit Public Key)

curl -s -X POST https://api.commune.email/v1/auth/agent-register \
  -H "Content-Type: application/json" \
  -d '{
    "agentName":  "My Agent",
    "orgName":    "My Org",
    "orgSlug":    "myorg",
    "publicKey":  "YOUR_BASE64_PUBLIC_KEY=="
  }' | jq .
# → { agentSignupToken, challenge, expiresIn: 900 }

Step 2: Sign Challenge + Verify

import base64, requests
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

priv_bytes = base64.b64decode("YOUR_PRIVATE_KEY")
private_key = Ed25519PrivateKey.from_private_bytes(priv_bytes)
challenge = "CHALLENGE_FROM_STEP_1"
sig = base64.b64encode(private_key.sign(challenge.encode())).decode()

r = requests.post("https://api.commune.email/v1/auth/agent-verify", json={
    "agentSignupToken": "TOKEN_FROM_STEP_1",
    "signature": sig,
})
print(r.json())
# → { agentId, orgId, inboxEmail: "myorg@commune.ai" }

After verification you can also authenticate every request with Ed25519 instead of API key:

Authorization: Agent {agentId}:{base64_ed25519_signature_of_request_body}

Data Deletion

Requires API key with admin or data:delete permission.

Create Deletion Request (Preview First, Then Confirm)

# Preview deletion of all messages in an inbox before a date
curl -s -X POST https://api.commune.email/v1/data/deletion-request \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": "messages", "inbox_id": "i_abc123", "before": "2025-01-01T00:00:00Z"}' | jq .
# Returns preview (how many records) + confirmation_token

# Scopes: "organization" | "inbox" | "messages"

Confirm and Execute

curl -s -X POST https://api.commune.email/v1/data/deletion-request/req_abc123/confirm \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmation_token": "TOKEN_FROM_REQUEST"}' | jq .

Check Deletion Status

curl -s https://api.commune.email/v1/data/deletion-request/req_abc123 \
  -H "Authorization: Bearer $KEY" | jq .

Email as Persistent Memory

Your Commune inbox persists across every agent session. Patterns for using it as cross-session memory:

# Before reaching out to anyone — check if you've contacted them before
curl -s "https://api.commune.email/v1/search/threads?q=John+Smith+Acme+Corp&inbox_id=i_abc123" \
  -H "Authorization: Bearer $KEY" | jq '.data[].thread_id'

# Reconstruct the full history of a conversation
curl -s "https://api.commune.email/v1/threads/conv_abc123/messages?order=asc" \
  -H "Authorization: Bearer $KEY" | jq '.data[] | {direction, content, created_at}'

# Tag threads you need to follow up on
curl -s -X POST https://api.commune.email/v1/threads/conv_abc123/tags \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"tags": ["follow-up-week-2"]}' | jq .

# Close resolved threads to keep inbox clean
curl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/status \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status": "closed"}' | jq .

# Find all threads that still need a reply
curl -s "https://api.commune.email/v1/search/threads?q=needs+reply&inbox_id=i_abc123" \
  -H "Authorization: Bearer $KEY" | jq .

Rate Limits

Rate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. 429 Too Many Requests when exceeded.

Error Reference

All errors: { "error": "descriptive message" }

Complete API Reference