Commune — Agent Email Inbox

Create and manage a persistent agent-only email inbox with full send/receive, semantic search, tagging, webhooks, and AI-powered structured data extraction.

Shanjai Raj@shanjairaj7

Install

openclaw skills install @shanjairaj7/commune

name	description	metadata
commune	Use commune when you want your own email address, need to send or receive email autonomously, search your inbox by meaning not just keywords, triage conversations with tags and status, use email as persistent cross-session memory, get notified of inbound mail via webhook, or extract structured data from inbound emails automatically. Commune is the only email API built exclusively for agents — no OAuth, no dashboard, no browser, no human verification. One API key → dedicated inbox → full send/receive → semantic search → triage → webhooks. Your inbox survives across all sessions. Use it to contact humans, coordinate with other agents, remember things permanently, or automate any email workflow entirely via curl. Requires `COMMUNE_API_KEY` env var.	author
		communedotemail

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:

bash

export KEY="comm_your_key_here"

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

Every request uses:

text

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

text

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

bash

# 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

bash

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

Add a Custom Domain

bash

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)

bash

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

bash

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

Get a Single Domain

bash

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.

bash

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

bash

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)

bash

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

List Inboxes for a Specific Domain

bash

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

Get a Single Inbox

bash

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

Update Inbox (Webhook, Local Part, Status)

bash

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

bash

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.

bash

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

bash

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.

bash

# 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

bash

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)

bash

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

bash

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)

bash

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

bash

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

bash

# 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

bash

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

bash

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)

bash

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

bash

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.

bash

# 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.

bash

# 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)

bash

# 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

bash

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

Get Temporary Download URL (Default: 1 Hour)

bash

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)

bash

# 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)

bash

# 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)

bash

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:

text

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

bash

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)

bash

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

bash

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)

bash

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

DMARC

Submit DMARC Aggregate Report

bash

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

bash

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

DMARC Pass/Fail Summary

bash

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

bash

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

Update Org Name

bash

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

bash

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

Create Scoped API Key (Least-Privilege Pattern)

bash

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)

bash

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

Revoke a Key

bash

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

python

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)

bash

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

python

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:

text

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)

bash

# 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

bash

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

bash

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:

bash

# 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

Tier	Per Hour	Per Day
Free	100 emails	1,000 emails
Pro	10,000 emails	100,000 emails
Enterprise	Custom	Custom

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

Error Reference

Status	Meaning
400	Bad request / missing required field
401	Invalid or missing API key
403	API key lacks required permission scope
404	Resource not found
409	Conflict — e.g. org slug already taken
410	Confirmation token expired
413	Attachment storage quota exceeded
429	Rate limit hit — check Retry-After header
500	Server error

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

Complete API Reference

Method	Endpoint	Scope Needed	What It Does
GET	/v1/domains	domains:read	List all domains
POST	/v1/domains	domains:write	Create custom domain
GET	/v1/domains/:id	domains:read	Get domain details
POST	/v1/domains/:id/verify	domains:write	Trigger DNS check
GET	/v1/domains/:id/records	domains:read	Get DNS records to configure
POST	/v1/inboxes	inboxes:write	Create inbox (auto-domain)
GET	/v1/inboxes	inboxes:read	List all inboxes
GET	/v1/domains/:d/inboxes	inboxes:read	List inboxes for a domain
POST	/v1/domains/:d/inboxes	inboxes:write	Create inbox under domain
GET	/v1/domains/:d/inboxes/:i	inboxes:read	Get inbox
PUT	/v1/domains/:d/inboxes/:i	inboxes:write	Update inbox
DELETE	/v1/domains/:d/inboxes/:i	inboxes:write	Delete inbox
PUT	/v1/domains/:d/inboxes/:i/extraction-schema	inboxes:write	Set AI extraction schema
DELETE	/v1/domains/:d/inboxes/:i/extraction-schema	inboxes:write	Remove extraction schema
GET	/v1/threads	threads:read	List threads (paginated)
GET	/v1/threads/:id/messages	threads:read	Get full conversation
GET	/v1/threads/:id/metadata	threads:read	Get tags/status/assignee
PUT	/v1/threads/:id/status	threads:write	Set status
POST	/v1/threads/:id/tags	threads:write	Add tags
DELETE	/v1/threads/:id/tags	threads:write	Remove tags
PUT	/v1/threads/:id/assign	threads:write	Assign/unassign thread
POST	/v1/messages/send	messages:write	Send email
GET	/v1/messages	messages:read	List messages (filter required)
GET	/v1/search/threads	threads:read	Semantic/vector search
POST	/v1/attachments/upload	attachments:write	Upload file (base64)
GET	/v1/attachments/:id	attachments:read	Get attachment metadata
GET	/v1/attachments/:id/url	attachments:read	Get signed download URL
GET	/v1/delivery/metrics	messages:read	Delivery stats
GET	/v1/delivery/events	messages:read	Per-message event log
GET	/v1/delivery/suppressions	messages:read	Bounced/complained addresses
GET	/v1/webhooks/deliveries	messages:read	List webhook deliveries
GET	/v1/webhooks/deliveries/:id	messages:read	Full delivery detail
POST	/v1/webhooks/deliveries/:id/retry	messages:write	Retry dead delivery
GET	/v1/webhooks/health	messages:read	Per-endpoint health stats
POST	/v1/dmarc/reports	domains:write	Submit DMARC XML report
GET	/v1/dmarc/reports	domains:read	List DMARC reports
GET	/v1/dmarc/summary	domains:read	DMARC pass/fail summary
GET	/v1/agent/org	—	Get own org
PATCH	/v1/agent/org	—	Update org name
GET	/v1/agent/api-keys	—	List API keys
POST	/v1/agent/api-keys	—	Create scoped API key
DELETE	/v1/agent/api-keys/:id	—	Revoke key
POST	/v1/agent/api-keys/:id/rotate	—	Rotate key
POST	/v1/auth/agent-register	public	Register (Ed25519 public key)
POST	/v1/auth/agent-verify	public	Verify challenge → activate
POST	/v1/data/deletion-request	admin/data:delete	Create deletion request
POST	/v1/data/deletion-request/:id/confirm	admin/data:delete	Execute deletion
GET	/v1/data/deletion-request/:id	admin/data:delete	Check deletion status

Commune — Agent Email Inbox

Install

Commune — Email for Agents

Why Commune — 5 Agent Superpowers

Architecture

60-Second Setup

Domains

List All Domains

Add a Custom Domain

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

Trigger DNS Verification

Get a Single Domain

Inboxes

Create Inbox — Auto Domain (Fastest Path)

Create Inbox Under Your Custom Domain

List All Inboxes (All Domains)

List Inboxes for a Specific Domain

Get a Single Inbox

Update Inbox (Webhook, Local Part, Status)

Delete Inbox

⚡ Set Structured Extraction Schema (AI Superpower)

Remove Extraction Schema

Threads

List Threads (Cursor-Paginated)

Get All Messages in a Thread

Get Thread Triage State (Tags, Status, Assignee)

Set Thread Status

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

Remove Tags from Thread

Assign Thread to an Agent/User

Messages

Send Email

Send HTML Email

Reply In-Thread (Maintains Email Threading Headers)

Send with CC, BCC, Reply-To

List Messages with Filters

⚡ Semantic Search

Attachments

Upload an Attachment (Use Before Sending)

Get Attachment Metadata

Get Temporary Download URL (Default: 1 Hour)

Delivery Monitoring

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

Delivery Event Log (Per-Message Tracking)

Suppression List (Addresses That Bounced or Complained)

Webhooks

⚡ Webhook Payload Verification (HMAC-SHA256)

List Webhook Deliveries

Get Full Delivery Detail (With Attempt History)

Retry a Dead or Failed Delivery

Endpoint Health Stats (Success Rate, Latency Per Endpoint)

DMARC

Submit DMARC Aggregate Report

List DMARC Reports

DMARC Pass/Fail Summary

Agent Self-Management (No Dashboard Needed)

Get Your Org

Update Org Name

List API Keys

Create Scoped API Key (Least-Privilege Pattern)

Rotate a Key (Invalidates Old, Returns New)

Revoke a Key

Agentless Registration (Ed25519 — Zero Human Involvement)

Generate Ed25519 Keypair

Step 1: Register (Submit Public Key)

Step 2: Sign Challenge + Verify

Data Deletion

Create Deletion Request (Preview First, Then Confirm)

Confirm and Execute

Check Deletion Status

Email as Persistent Memory

Rate Limits

Error Reference

Complete API Reference

Related skills