{ "schemaVersion": "1.0", "item": { "slug": "commune", "name": "Commune — Agent Email Inbox", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/shanjairaj7/commune", "canonicalUrl": "https://clawhub.ai/shanjairaj7/commune", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/commune", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=commune", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "INSTALL.md", "SKILL.md", "scripts/commune.py", "references/api.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "slug": "commune", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-02T01:09:03.005Z", "expiresAt": "2026-05-09T01:09:03.005Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=commune", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=commune", "contentDisposition": "attachment; filename=\"commune-1.0.1.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "commune" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/commune" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/commune", "agentPageUrl": "https://openagent3.xyz/skills/commune/agent", "manifestUrl": "https://openagent3.xyz/skills/commune/agent.json", "briefUrl": "https://openagent3.xyz/skills/commune/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Commune — Email for Agents", "body": "Every agent deserves its own email address.\n\nCommune 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.\n\nBase URL: https://api.commune.email\n\nSet your key once:\n\nexport KEY=\"comm_your_key_here\"\n\nGet your key at commune.email → API Keys. The key prefix is comm_.\n\nEvery request uses:\n\nAuthorization: Bearer $KEY" }, { "title": "Why Commune — 5 Agent Superpowers", "body": "1. Agent-Native Identity\nGet 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.\n\n2. Semantic Search Across All Conversations\nFind 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.\n\n3. Built-in Triage Primitives\nTag 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.\n\n4. Structured Extraction from Inbound Email\nConfigure 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.\n\n5. Webhook Push + HMAC Verification\nGet instant HTTP notifications when email arrives. Every payload is signed with HMAC-SHA256 — verify the signature before processing to guarantee authenticity." }, { "title": "Architecture", "body": "Domain → Inbox → Thread → Message\n\nDomain — An email domain (company.com). Shared domain auto-assigned — no DNS setup required.\nInbox — A mailbox under a domain (agent@company.com). One agent = one inbox (or more).\nThread — A conversation (emails grouped by subject/reply chain). Has tags, status, assignee.\nMessage — A single email (inbound or outbound) inside a thread.\n\nPermission scopes on API keys:\ndomains:read domains:write inboxes:read inboxes:write threads:read threads:write messages:read messages:write attachments:read attachments:write" }, { "title": "60-Second Setup", "body": "# Step 1: Get your inbox (auto-domain, no DNS needed)\ncurl -s -X POST https://api.commune.email/v1/inboxes \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"local_part\": \"myagent\", \"name\": \"My Agent\"}' | jq .\n\n# Response gives you an email address immediately:\n# \"address\": \"myagent@commune.ai\"\n# Save the \"id\" field as your INBOX_ID\n\n# Step 2: Send your first email\ncurl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"someone@example.com\",\n \"subject\": \"Hello from my agent\",\n \"text\": \"I am an AI agent with my own email address.\",\n \"inbox_id\": \"i_your_inbox_id\"\n }' | jq .\n\n# Step 3: Check what arrived\ncurl -s \"https://api.commune.email/v1/threads?inbox_id=i_your_inbox_id&limit=20\" \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "List All Domains", "body": "curl -s https://api.commune.email/v1/domains \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Add a Custom Domain", "body": "curl -s -X POST https://api.commune.email/v1/domains \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"mycompany.com\"}' | jq .\n# Returns domain_id — use in /records to get DNS entries" }, { "title": "Get DNS Records to Configure (MX, SPF, DKIM, DMARC)", "body": "curl -s https://api.commune.email/v1/domains/d_abc123/records \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# Add these at your DNS registrar, then verify" }, { "title": "Trigger DNS Verification", "body": "curl -s -X POST https://api.commune.email/v1/domains/d_abc123/verify \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Get a Single Domain", "body": "curl -s https://api.commune.email/v1/domains/d_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Create Inbox — Auto Domain (Fastest Path)", "body": "No DNS, no domain required. Auto-assigns to the shared Commune domain.\n\ncurl -s -X POST https://api.commune.email/v1/inboxes \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"local_part\": \"sales-agent\",\n \"name\": \"Sales Agent\",\n \"webhook\": {\n \"endpoint\": \"https://your-server.com/email-hook\",\n \"events\": [\"inbound\"]\n }\n }' | jq .\n# → address: \"sales-agent@commune.ai\"" }, { "title": "Create Inbox Under Your Custom Domain", "body": "curl -s -X POST https://api.commune.email/v1/domains/d_abc123/inboxes \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"local_part\": \"support\", \"name\": \"Support Inbox\"}' | jq .\n# → address: \"support@mycompany.com\"" }, { "title": "List All Inboxes (All Domains)", "body": "curl -s https://api.commune.email/v1/inboxes \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "List Inboxes for a Specific Domain", "body": "curl -s \"https://api.commune.email/v1/domains/d_abc123/inboxes\" \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Get a Single Inbox", "body": "curl -s https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Update Inbox (Webhook, Local Part, Status)", "body": "curl -s -X PUT https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123 \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"webhook\": {\n \"endpoint\": \"https://new-server.com/hook\",\n \"events\": [\"inbound\"]\n }\n }' | jq ." }, { "title": "Delete Inbox", "body": "curl -s -X DELETE https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "⚡ Set Structured Extraction Schema (AI Superpower)", "body": "Configure once. Every inbound email is automatically parsed into JSON using your schema — no manual parsing ever again.\n\ncurl -s -X PUT \\\n https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123/extraction-schema \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"support_ticket\",\n \"description\": \"Extract structured data from customer support emails\",\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"order_id\": { \"type\": \"string\" },\n \"issue_type\": { \"type\": \"string\", \"enum\": [\"shipping\", \"billing\", \"product\", \"refund\", \"other\"] },\n \"urgency\": { \"type\": \"string\", \"enum\": [\"low\", \"medium\", \"high\", \"critical\"] },\n \"customer_name\": { \"type\": \"string\" },\n \"wants_refund\": { \"type\": \"boolean\" }\n }\n },\n \"enabled\": true\n }' | jq .\n# Now every inbound email is auto-parsed — check message.extracted_data" }, { "title": "Remove Extraction Schema", "body": "curl -s -X DELETE \\\n https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123/extraction-schema \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "List Threads (Cursor-Paginated)", "body": "Requires inbox_id OR domain_id. Default: newest first, 20 per page.\n\n# Newest 20 threads in your inbox\ncurl -s \"https://api.commune.email/v1/threads?inbox_id=i_abc123&limit=20\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Oldest first (useful for processing in order)\ncurl -s \"https://api.commune.email/v1/threads?inbox_id=i_abc123&order=asc&limit=50\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Next page (use next_cursor from previous response)\ncurl -s \"https://api.commune.email/v1/threads?inbox_id=i_abc123&cursor=eyJsYXN0S2V5Ijo...\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nResponse 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." }, { "title": "Get All Messages in a Thread", "body": "curl -s \"https://api.commune.email/v1/threads/conv_abc123/messages?order=asc\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nMessage fields: message_id, thread_id, direction, participants (array with role + identity), content (plain text), content_html, attachments, created_at, metadata.subject." }, { "title": "Get Thread Triage State (Tags, Status, Assignee)", "body": "curl -s https://api.commune.email/v1/threads/conv_abc123/metadata \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# → { thread_id, tags: [\"vip\"], status: \"needs_reply\", assigned_to: \"agent-007\" }" }, { "title": "Set Thread Status", "body": "Statuses: open needs_reply waiting closed\n\ncurl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/status \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"status\": \"closed\"}' | jq ." }, { "title": "Add Tags to Thread (Non-Destructive — Existing Tags Preserved)", "body": "curl -s -X POST https://api.commune.email/v1/threads/conv_abc123/tags \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"tags\": [\"urgent\", \"vip\", \"sales-lead\", \"follow-up\"]}' | jq ." }, { "title": "Remove Tags from Thread", "body": "curl -s -X DELETE https://api.commune.email/v1/threads/conv_abc123/tags \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"tags\": [\"urgent\"]}' | jq ." }, { "title": "Assign Thread to an Agent/User", "body": "# Assign\ncurl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/assign \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"assigned_to\": \"agent-billing\"}' | jq .\n\n# Unassign\ncurl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/assign \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"assigned_to\": null}' | jq ." }, { "title": "Send Email", "body": "curl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"user@example.com\",\n \"subject\": \"Hello\",\n \"text\": \"Plain text body.\",\n \"inbox_id\": \"i_abc123\"\n }' | jq ." }, { "title": "Send HTML Email", "body": "curl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"user@example.com\",\n \"subject\": \"Your Report\",\n \"html\": \"

Report Ready

See attached.

\",\n \"text\": \"Report ready — see attached.\",\n \"inbox_id\": \"i_abc123\",\n \"attachments\": [\"att_abc123\"]\n }' | jq ." }, { "title": "Reply In-Thread (Maintains Email Threading Headers)", "body": "curl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"user@example.com\",\n \"subject\": \"Re: Your question\",\n \"text\": \"We resolved your issue — here is what we did.\",\n \"thread_id\": \"conv_abc123\",\n \"inbox_id\": \"i_abc123\"\n }' | jq ." }, { "title": "Send with CC, BCC, Reply-To", "body": "curl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": [\"alice@example.com\", \"bob@example.com\"],\n \"cc\": \"manager@example.com\",\n \"bcc\": \"audit@mycompany.com\",\n \"reply_to\": \"support@mycompany.com\",\n \"subject\": \"Invoice #1042\",\n \"html\": \"

Please find your invoice attached.

\",\n \"text\": \"Please find your invoice attached.\",\n \"inbox_id\": \"i_abc123\"\n }' | jq .\n\nAll 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)." }, { "title": "List Messages with Filters", "body": "At least one filter required: inbox_id, domain_id, or sender.\n\n# All messages in an inbox\ncurl -s \"https://api.commune.email/v1/messages?inbox_id=i_abc123&limit=50&order=desc\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Messages from a specific sender\ncurl -s \"https://api.commune.email/v1/messages?sender=john@corp.com&limit=20\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Date range\ncurl -s \"https://api.commune.email/v1/messages?inbox_id=i_abc123&after=2025-01-01T00:00:00Z&before=2025-02-01T00:00:00Z\" \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "⚡ Semantic Search", "body": "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.\n\n# Find threads about a topic\ncurl -s \"https://api.commune.email/v1/search/threads?q=customer+unhappy+with+shipping&inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Cross-domain search\ncurl -s \"https://api.commune.email/v1/search/threads?q=refund+request&domain_id=d_abc123&limit=10\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Find your own past outreach\ncurl -s \"https://api.commune.email/v1/search/threads?q=partnership+proposal&inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nParameters: q (required), inbox_id OR domain_id (one required), limit (1–100, default 20).\n\nResponse includes score per result (relevance, 0–1) and search_type (vector or regex)." }, { "title": "Upload an Attachment (Use Before Sending)", "body": "# Encode file to base64 first\nB64=$(base64 -w0 /path/to/invoice.pdf)\n\ncurl -s -X POST https://api.commune.email/v1/attachments/upload \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"content\\\": \\\"$B64\\\", \\\"filename\\\": \\\"invoice.pdf\\\", \\\"mime_type\\\": \\\"application/pdf\\\"}\" | jq .\n\n# → { \"data\": { \"attachment_id\": \"att_abc123\", \"size\": 45230 } }\n# Use attachment_id in the \"attachments\" array when sending email" }, { "title": "Get Attachment Metadata", "body": "curl -s https://api.commune.email/v1/attachments/att_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Get Temporary Download URL (Default: 1 Hour)", "body": "curl -s \"https://api.commune.email/v1/attachments/att_abc123/url?expires_in=3600\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# → { \"data\": { \"url\": \"https://...\", \"expires_in\": 3600, \"filename\": \"invoice.pdf\" } }" }, { "title": "Delivery Metrics (Sent / Delivered / Bounced / Complained / Suppressed)", "body": "# Last 7 days\ncurl -s \"https://api.commune.email/v1/delivery/metrics?inbox_id=i_abc123&period=7d\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# 30 days\ncurl -s \"https://api.commune.email/v1/delivery/metrics?inbox_id=i_abc123&period=30d\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Custom period (max 90 days)\ncurl -s \"https://api.commune.email/v1/delivery/metrics?inbox_id=i_abc123&days=14\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nReturns: sent, delivered, bounced, complained, failed, suppressed counts + computed delivery_rate, bounce_rate, complaint_rate." }, { "title": "Delivery Event Log (Per-Message Tracking)", "body": "# All events for an inbox\ncurl -s \"https://api.commune.email/v1/delivery/events?inbox_id=i_abc123&limit=50\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Filter by event type: sent | delivered | bounced | complained | failed\ncurl -s \"https://api.commune.email/v1/delivery/events?inbox_id=i_abc123&event_type=bounced\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Track a specific message\ncurl -s \"https://api.commune.email/v1/delivery/events?message_id=msg_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Suppression List (Addresses That Bounced or Complained)", "body": "curl -s \"https://api.commune.email/v1/delivery/suppressions?inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# Check this before sending to avoid reputation damage" }, { "title": "⚡ Webhook Payload Verification (HMAC-SHA256)", "body": "Every inbound webhook is signed. Always verify before processing:\n\nHeaders:\n x-commune-signature: v1=5a3f2b...\n x-commune-timestamp: 1707667200000\n\nVerify by computing HMAC-SHA256(key=webhook_secret, message=timestamp + \".\" + raw_body_string) and comparing to the v1= value." }, { "title": "List Webhook Deliveries", "body": "curl -s \"https://api.commune.email/v1/webhooks/deliveries?inbox_id=i_abc123&limit=50\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Filter by status: pending | delivered | failed | dead\ncurl -s \"https://api.commune.email/v1/webhooks/deliveries?status=failed\" \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Get Full Delivery Detail (With Attempt History)", "body": "curl -s https://api.commune.email/v1/webhooks/deliveries/wdel_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# Returns attempt_count, last_error, last_status_code, delivery_latency_ms, next_retry_at" }, { "title": "Retry a Dead or Failed Delivery", "body": "curl -s -X POST https://api.commune.email/v1/webhooks/deliveries/wdel_abc123/retry \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Endpoint Health Stats (Success Rate, Latency Per Endpoint)", "body": "curl -s https://api.commune.email/v1/webhooks/health \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Submit DMARC Aggregate Report", "body": "curl -s -X POST \"https://api.commune.email/v1/dmarc/reports?domain_id=d_abc123\" \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/xml\" \\\n --data-binary @dmarc-report.xml | jq .\n# Also accepts application/gzip and application/zip" }, { "title": "List DMARC Reports", "body": "curl -s \"https://api.commune.email/v1/dmarc/reports?domain=mycompany.com&limit=50\" \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "DMARC Pass/Fail Summary", "body": "curl -s \"https://api.commune.email/v1/dmarc/summary?domain=mycompany.com&days=30\" \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Get Your Org", "body": "curl -s https://api.commune.email/v1/agent/org \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Update Org Name", "body": "curl -s -X PATCH https://api.commune.email/v1/agent/org \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"My Agent Organization\"}' | jq ." }, { "title": "List API Keys", "body": "curl -s https://api.commune.email/v1/agent/api-keys \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Create Scoped API Key (Least-Privilege Pattern)", "body": "curl -s -X POST https://api.commune.email/v1/agent/api-keys \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"outbound-only\",\n \"permissions\": [\"messages:write\", \"inboxes:read\", \"threads:read\"]\n }' | jq .\n# Raw comm_ key shown ONCE — store immediately in env or secrets manager" }, { "title": "Rotate a Key (Invalidates Old, Returns New)", "body": "curl -s -X POST https://api.commune.email/v1/agent/api-keys/key_abc123/rotate \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Revoke a Key", "body": "curl -s -X DELETE https://api.commune.email/v1/agent/api-keys/key_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Agentless Registration (Ed25519 — Zero Human Involvement)", "body": "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." }, { "title": "Generate Ed25519 Keypair", "body": "from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey\nimport base64\n\nprivate_key = Ed25519PrivateKey.generate()\npub = base64.b64encode(private_key.public_key().public_bytes_raw()).decode()\npriv = base64.b64encode(private_key.private_bytes_raw()).decode()\nprint(\"PUBLIC :\", pub) # 44 chars, ends with =\nprint(\"PRIVATE:\", priv) # store securely" }, { "title": "Step 1: Register (Submit Public Key)", "body": "curl -s -X POST https://api.commune.email/v1/auth/agent-register \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"agentName\": \"My Agent\",\n \"orgName\": \"My Org\",\n \"orgSlug\": \"myorg\",\n \"publicKey\": \"YOUR_BASE64_PUBLIC_KEY==\"\n }' | jq .\n# → { agentSignupToken, challenge, expiresIn: 900 }" }, { "title": "Step 2: Sign Challenge + Verify", "body": "import base64, requests\nfrom cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey\n\npriv_bytes = base64.b64decode(\"YOUR_PRIVATE_KEY\")\nprivate_key = Ed25519PrivateKey.from_private_bytes(priv_bytes)\nchallenge = \"CHALLENGE_FROM_STEP_1\"\nsig = base64.b64encode(private_key.sign(challenge.encode())).decode()\n\nr = requests.post(\"https://api.commune.email/v1/auth/agent-verify\", json={\n \"agentSignupToken\": \"TOKEN_FROM_STEP_1\",\n \"signature\": sig,\n})\nprint(r.json())\n# → { agentId, orgId, inboxEmail: \"myorg@commune.ai\" }\n\nAfter verification you can also authenticate every request with Ed25519 instead of API key:\n\nAuthorization: Agent {agentId}:{base64_ed25519_signature_of_request_body}" }, { "title": "Data Deletion", "body": "Requires API key with admin or data:delete permission." }, { "title": "Create Deletion Request (Preview First, Then Confirm)", "body": "# Preview deletion of all messages in an inbox before a date\ncurl -s -X POST https://api.commune.email/v1/data/deletion-request \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"scope\": \"messages\", \"inbox_id\": \"i_abc123\", \"before\": \"2025-01-01T00:00:00Z\"}' | jq .\n# Returns preview (how many records) + confirmation_token\n\n# Scopes: \"organization\" | \"inbox\" | \"messages\"" }, { "title": "Confirm and Execute", "body": "curl -s -X POST https://api.commune.email/v1/data/deletion-request/req_abc123/confirm \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"confirmation_token\": \"TOKEN_FROM_REQUEST\"}' | jq ." }, { "title": "Check Deletion Status", "body": "curl -s https://api.commune.email/v1/data/deletion-request/req_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Email as Persistent Memory", "body": "Your Commune inbox persists across every agent session. Patterns for using it as cross-session memory:\n\n# Before reaching out to anyone — check if you've contacted them before\ncurl -s \"https://api.commune.email/v1/search/threads?q=John+Smith+Acme+Corp&inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq '.data[].thread_id'\n\n# Reconstruct the full history of a conversation\ncurl -s \"https://api.commune.email/v1/threads/conv_abc123/messages?order=asc\" \\\n -H \"Authorization: Bearer $KEY\" | jq '.data[] | {direction, content, created_at}'\n\n# Tag threads you need to follow up on\ncurl -s -X POST https://api.commune.email/v1/threads/conv_abc123/tags \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"tags\": [\"follow-up-week-2\"]}' | jq .\n\n# Close resolved threads to keep inbox clean\ncurl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/status \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"status\": \"closed\"}' | jq .\n\n# Find all threads that still need a reply\ncurl -s \"https://api.commune.email/v1/search/threads?q=needs+reply&inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq ." }, { "title": "Rate Limits", "body": "TierPer HourPer DayFree100 emails1,000 emailsPro10,000 emails100,000 emailsEnterpriseCustomCustom\n\nRate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.\n429 Too Many Requests when exceeded." }, { "title": "Error Reference", "body": "StatusMeaning400Bad request / missing required field401Invalid or missing API key403API key lacks required permission scope404Resource not found409Conflict — e.g. org slug already taken410Confirmation token expired413Attachment storage quota exceeded429Rate limit hit — check Retry-After header500Server error\n\nAll errors: { \"error\": \"descriptive message\" }" }, { "title": "Complete API Reference", "body": "MethodEndpointScope NeededWhat It DoesGET/v1/domainsdomains:readList all domainsPOST/v1/domainsdomains:writeCreate custom domainGET/v1/domains/:iddomains:readGet domain detailsPOST/v1/domains/:id/verifydomains:writeTrigger DNS checkGET/v1/domains/:id/recordsdomains:readGet DNS records to configurePOST/v1/inboxesinboxes:writeCreate inbox (auto-domain)GET/v1/inboxesinboxes:readList all inboxesGET/v1/domains/:d/inboxesinboxes:readList inboxes for a domainPOST/v1/domains/:d/inboxesinboxes:writeCreate inbox under domainGET/v1/domains/:d/inboxes/:iinboxes:readGet inboxPUT/v1/domains/:d/inboxes/:iinboxes:writeUpdate inboxDELETE/v1/domains/:d/inboxes/:iinboxes:writeDelete inboxPUT/v1/domains/:d/inboxes/:i/extraction-schemainboxes:writeSet AI extraction schemaDELETE/v1/domains/:d/inboxes/:i/extraction-schemainboxes:writeRemove extraction schemaGET/v1/threadsthreads:readList threads (paginated)GET/v1/threads/:id/messagesthreads:readGet full conversationGET/v1/threads/:id/metadatathreads:readGet tags/status/assigneePUT/v1/threads/:id/statusthreads:writeSet statusPOST/v1/threads/:id/tagsthreads:writeAdd tagsDELETE/v1/threads/:id/tagsthreads:writeRemove tagsPUT/v1/threads/:id/assignthreads:writeAssign/unassign threadPOST/v1/messages/sendmessages:writeSend emailGET/v1/messagesmessages:readList messages (filter required)GET/v1/search/threadsthreads:readSemantic/vector searchPOST/v1/attachments/uploadattachments:writeUpload file (base64)GET/v1/attachments/:idattachments:readGet attachment metadataGET/v1/attachments/:id/urlattachments:readGet signed download URLGET/v1/delivery/metricsmessages:readDelivery statsGET/v1/delivery/eventsmessages:readPer-message event logGET/v1/delivery/suppressionsmessages:readBounced/complained addressesGET/v1/webhooks/deliveriesmessages:readList webhook deliveriesGET/v1/webhooks/deliveries/:idmessages:readFull delivery detailPOST/v1/webhooks/deliveries/:id/retrymessages:writeRetry dead deliveryGET/v1/webhooks/healthmessages:readPer-endpoint health statsPOST/v1/dmarc/reportsdomains:writeSubmit DMARC XML reportGET/v1/dmarc/reportsdomains:readList DMARC reportsGET/v1/dmarc/summarydomains:readDMARC pass/fail summaryGET/v1/agent/org—Get own orgPATCH/v1/agent/org—Update org nameGET/v1/agent/api-keys—List API keysPOST/v1/agent/api-keys—Create scoped API keyDELETE/v1/agent/api-keys/:id—Revoke keyPOST/v1/agent/api-keys/:id/rotate—Rotate keyPOST/v1/auth/agent-registerpublicRegister (Ed25519 public key)POST/v1/auth/agent-verifypublicVerify challenge → activatePOST/v1/data/deletion-requestadmin/data:deleteCreate deletion requestPOST/v1/data/deletion-request/:id/confirmadmin/data:deleteExecute deletionGET/v1/data/deletion-request/:idadmin/data:deleteCheck deletion status" } ], "body": "name\tdescription\tmetadata\ncommune\tUse 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.\tauthor\n\t\tcommunedotemail\nCommune — Email for Agents\n\nEvery agent deserves its own email address.\n\nCommune 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.\n\nBase URL: https://api.commune.email\n\nSet your key once:\n\nexport KEY=\"comm_your_key_here\"\n\n\nGet your key at commune.email → API Keys. The key prefix is comm_.\n\nEvery request uses:\n\nAuthorization: Bearer $KEY\n\nWhy Commune — 5 Agent Superpowers\n\n1. 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.\n\n2. 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.\n\n3. 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.\n\n4. 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.\n\n5. 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.\n\nArchitecture\nDomain → Inbox → Thread → Message\n\nDomain — An email domain (company.com). Shared domain auto-assigned — no DNS setup required.\nInbox — A mailbox under a domain (agent@company.com). One agent = one inbox (or more).\nThread — A conversation (emails grouped by subject/reply chain). Has tags, status, assignee.\nMessage — A single email (inbound or outbound) inside a thread.\n\nPermission scopes on API keys: domains:read domains:write inboxes:read inboxes:write threads:read threads:write messages:read messages:write attachments:read attachments:write\n\n60-Second Setup\n# Step 1: Get your inbox (auto-domain, no DNS needed)\ncurl -s -X POST https://api.commune.email/v1/inboxes \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"local_part\": \"myagent\", \"name\": \"My Agent\"}' | jq .\n\n# Response gives you an email address immediately:\n# \"address\": \"myagent@commune.ai\"\n# Save the \"id\" field as your INBOX_ID\n\n# Step 2: Send your first email\ncurl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"someone@example.com\",\n \"subject\": \"Hello from my agent\",\n \"text\": \"I am an AI agent with my own email address.\",\n \"inbox_id\": \"i_your_inbox_id\"\n }' | jq .\n\n# Step 3: Check what arrived\ncurl -s \"https://api.commune.email/v1/threads?inbox_id=i_your_inbox_id&limit=20\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nDomains\nList All Domains\ncurl -s https://api.commune.email/v1/domains \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nAdd a Custom Domain\ncurl -s -X POST https://api.commune.email/v1/domains \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"mycompany.com\"}' | jq .\n# Returns domain_id — use in /records to get DNS entries\n\nGet DNS Records to Configure (MX, SPF, DKIM, DMARC)\ncurl -s https://api.commune.email/v1/domains/d_abc123/records \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# Add these at your DNS registrar, then verify\n\nTrigger DNS Verification\ncurl -s -X POST https://api.commune.email/v1/domains/d_abc123/verify \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nGet a Single Domain\ncurl -s https://api.commune.email/v1/domains/d_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nInboxes\nCreate Inbox — Auto Domain (Fastest Path)\n\nNo DNS, no domain required. Auto-assigns to the shared Commune domain.\n\ncurl -s -X POST https://api.commune.email/v1/inboxes \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"local_part\": \"sales-agent\",\n \"name\": \"Sales Agent\",\n \"webhook\": {\n \"endpoint\": \"https://your-server.com/email-hook\",\n \"events\": [\"inbound\"]\n }\n }' | jq .\n# → address: \"sales-agent@commune.ai\"\n\nCreate Inbox Under Your Custom Domain\ncurl -s -X POST https://api.commune.email/v1/domains/d_abc123/inboxes \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"local_part\": \"support\", \"name\": \"Support Inbox\"}' | jq .\n# → address: \"support@mycompany.com\"\n\nList All Inboxes (All Domains)\ncurl -s https://api.commune.email/v1/inboxes \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nList Inboxes for a Specific Domain\ncurl -s \"https://api.commune.email/v1/domains/d_abc123/inboxes\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nGet a Single Inbox\ncurl -s https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nUpdate Inbox (Webhook, Local Part, Status)\ncurl -s -X PUT https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123 \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"webhook\": {\n \"endpoint\": \"https://new-server.com/hook\",\n \"events\": [\"inbound\"]\n }\n }' | jq .\n\nDelete Inbox\ncurl -s -X DELETE https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n⚡ Set Structured Extraction Schema (AI Superpower)\n\nConfigure once. Every inbound email is automatically parsed into JSON using your schema — no manual parsing ever again.\n\ncurl -s -X PUT \\\n https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123/extraction-schema \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"support_ticket\",\n \"description\": \"Extract structured data from customer support emails\",\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"order_id\": { \"type\": \"string\" },\n \"issue_type\": { \"type\": \"string\", \"enum\": [\"shipping\", \"billing\", \"product\", \"refund\", \"other\"] },\n \"urgency\": { \"type\": \"string\", \"enum\": [\"low\", \"medium\", \"high\", \"critical\"] },\n \"customer_name\": { \"type\": \"string\" },\n \"wants_refund\": { \"type\": \"boolean\" }\n }\n },\n \"enabled\": true\n }' | jq .\n# Now every inbound email is auto-parsed — check message.extracted_data\n\nRemove Extraction Schema\ncurl -s -X DELETE \\\n https://api.commune.email/v1/domains/d_abc123/inboxes/i_abc123/extraction-schema \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nThreads\nList Threads (Cursor-Paginated)\n\nRequires inbox_id OR domain_id. Default: newest first, 20 per page.\n\n# Newest 20 threads in your inbox\ncurl -s \"https://api.commune.email/v1/threads?inbox_id=i_abc123&limit=20\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Oldest first (useful for processing in order)\ncurl -s \"https://api.commune.email/v1/threads?inbox_id=i_abc123&order=asc&limit=50\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Next page (use next_cursor from previous response)\ncurl -s \"https://api.commune.email/v1/threads?inbox_id=i_abc123&cursor=eyJsYXN0S2V5Ijo...\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n\nResponse 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.\n\nGet All Messages in a Thread\ncurl -s \"https://api.commune.email/v1/threads/conv_abc123/messages?order=asc\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n\nMessage fields: message_id, thread_id, direction, participants (array with role + identity), content (plain text), content_html, attachments, created_at, metadata.subject.\n\nGet Thread Triage State (Tags, Status, Assignee)\ncurl -s https://api.commune.email/v1/threads/conv_abc123/metadata \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# → { thread_id, tags: [\"vip\"], status: \"needs_reply\", assigned_to: \"agent-007\" }\n\nSet Thread Status\n\nStatuses: open needs_reply waiting closed\n\ncurl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/status \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"status\": \"closed\"}' | jq .\n\nAdd Tags to Thread (Non-Destructive — Existing Tags Preserved)\ncurl -s -X POST https://api.commune.email/v1/threads/conv_abc123/tags \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"tags\": [\"urgent\", \"vip\", \"sales-lead\", \"follow-up\"]}' | jq .\n\nRemove Tags from Thread\ncurl -s -X DELETE https://api.commune.email/v1/threads/conv_abc123/tags \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"tags\": [\"urgent\"]}' | jq .\n\nAssign Thread to an Agent/User\n# Assign\ncurl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/assign \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"assigned_to\": \"agent-billing\"}' | jq .\n\n# Unassign\ncurl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/assign \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"assigned_to\": null}' | jq .\n\nMessages\nSend Email\ncurl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"user@example.com\",\n \"subject\": \"Hello\",\n \"text\": \"Plain text body.\",\n \"inbox_id\": \"i_abc123\"\n }' | jq .\n\nSend HTML Email\ncurl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"user@example.com\",\n \"subject\": \"Your Report\",\n \"html\": \"

Report Ready

See attached.

\",\n \"text\": \"Report ready — see attached.\",\n \"inbox_id\": \"i_abc123\",\n \"attachments\": [\"att_abc123\"]\n }' | jq .\n\nReply In-Thread (Maintains Email Threading Headers)\ncurl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"user@example.com\",\n \"subject\": \"Re: Your question\",\n \"text\": \"We resolved your issue — here is what we did.\",\n \"thread_id\": \"conv_abc123\",\n \"inbox_id\": \"i_abc123\"\n }' | jq .\n\nSend with CC, BCC, Reply-To\ncurl -s -X POST https://api.commune.email/v1/messages/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": [\"alice@example.com\", \"bob@example.com\"],\n \"cc\": \"manager@example.com\",\n \"bcc\": \"audit@mycompany.com\",\n \"reply_to\": \"support@mycompany.com\",\n \"subject\": \"Invoice #1042\",\n \"html\": \"

Please find your invoice attached.

\",\n \"text\": \"Please find your invoice attached.\",\n \"inbox_id\": \"i_abc123\"\n }' | jq .\n\n\nAll 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).\n\nList Messages with Filters\n\nAt least one filter required: inbox_id, domain_id, or sender.\n\n# All messages in an inbox\ncurl -s \"https://api.commune.email/v1/messages?inbox_id=i_abc123&limit=50&order=desc\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Messages from a specific sender\ncurl -s \"https://api.commune.email/v1/messages?sender=john@corp.com&limit=20\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Date range\ncurl -s \"https://api.commune.email/v1/messages?inbox_id=i_abc123&after=2025-01-01T00:00:00Z&before=2025-02-01T00:00:00Z\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n⚡ Semantic Search\n\nSearch 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.\n\n# Find threads about a topic\ncurl -s \"https://api.commune.email/v1/search/threads?q=customer+unhappy+with+shipping&inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Cross-domain search\ncurl -s \"https://api.commune.email/v1/search/threads?q=refund+request&domain_id=d_abc123&limit=10\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Find your own past outreach\ncurl -s \"https://api.commune.email/v1/search/threads?q=partnership+proposal&inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n\nParameters: q (required), inbox_id OR domain_id (one required), limit (1–100, default 20).\n\nResponse includes score per result (relevance, 0–1) and search_type (vector or regex).\n\nAttachments\nUpload an Attachment (Use Before Sending)\n# Encode file to base64 first\nB64=$(base64 -w0 /path/to/invoice.pdf)\n\ncurl -s -X POST https://api.commune.email/v1/attachments/upload \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"content\\\": \\\"$B64\\\", \\\"filename\\\": \\\"invoice.pdf\\\", \\\"mime_type\\\": \\\"application/pdf\\\"}\" | jq .\n\n# → { \"data\": { \"attachment_id\": \"att_abc123\", \"size\": 45230 } }\n# Use attachment_id in the \"attachments\" array when sending email\n\nGet Attachment Metadata\ncurl -s https://api.commune.email/v1/attachments/att_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nGet Temporary Download URL (Default: 1 Hour)\ncurl -s \"https://api.commune.email/v1/attachments/att_abc123/url?expires_in=3600\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# → { \"data\": { \"url\": \"https://...\", \"expires_in\": 3600, \"filename\": \"invoice.pdf\" } }\n\nDelivery Monitoring\nDelivery Metrics (Sent / Delivered / Bounced / Complained / Suppressed)\n# Last 7 days\ncurl -s \"https://api.commune.email/v1/delivery/metrics?inbox_id=i_abc123&period=7d\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# 30 days\ncurl -s \"https://api.commune.email/v1/delivery/metrics?inbox_id=i_abc123&period=30d\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Custom period (max 90 days)\ncurl -s \"https://api.commune.email/v1/delivery/metrics?inbox_id=i_abc123&days=14\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n\nReturns: sent, delivered, bounced, complained, failed, suppressed counts + computed delivery_rate, bounce_rate, complaint_rate.\n\nDelivery Event Log (Per-Message Tracking)\n# All events for an inbox\ncurl -s \"https://api.commune.email/v1/delivery/events?inbox_id=i_abc123&limit=50\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Filter by event type: sent | delivered | bounced | complained | failed\ncurl -s \"https://api.commune.email/v1/delivery/events?inbox_id=i_abc123&event_type=bounced\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Track a specific message\ncurl -s \"https://api.commune.email/v1/delivery/events?message_id=msg_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nSuppression List (Addresses That Bounced or Complained)\ncurl -s \"https://api.commune.email/v1/delivery/suppressions?inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# Check this before sending to avoid reputation damage\n\nWebhooks\n⚡ Webhook Payload Verification (HMAC-SHA256)\n\nEvery inbound webhook is signed. Always verify before processing:\n\nHeaders:\n x-commune-signature: v1=5a3f2b...\n x-commune-timestamp: 1707667200000\n\n\nVerify by computing HMAC-SHA256(key=webhook_secret, message=timestamp + \".\" + raw_body_string) and comparing to the v1= value.\n\nList Webhook Deliveries\ncurl -s \"https://api.commune.email/v1/webhooks/deliveries?inbox_id=i_abc123&limit=50\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\n# Filter by status: pending | delivered | failed | dead\ncurl -s \"https://api.commune.email/v1/webhooks/deliveries?status=failed\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nGet Full Delivery Detail (With Attempt History)\ncurl -s https://api.commune.email/v1/webhooks/deliveries/wdel_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq .\n# Returns attempt_count, last_error, last_status_code, delivery_latency_ms, next_retry_at\n\nRetry a Dead or Failed Delivery\ncurl -s -X POST https://api.commune.email/v1/webhooks/deliveries/wdel_abc123/retry \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nEndpoint Health Stats (Success Rate, Latency Per Endpoint)\ncurl -s https://api.commune.email/v1/webhooks/health \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nDMARC\nSubmit DMARC Aggregate Report\ncurl -s -X POST \"https://api.commune.email/v1/dmarc/reports?domain_id=d_abc123\" \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/xml\" \\\n --data-binary @dmarc-report.xml | jq .\n# Also accepts application/gzip and application/zip\n\nList DMARC Reports\ncurl -s \"https://api.commune.email/v1/dmarc/reports?domain=mycompany.com&limit=50\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nDMARC Pass/Fail Summary\ncurl -s \"https://api.commune.email/v1/dmarc/summary?domain=mycompany.com&days=30\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nAgent Self-Management (No Dashboard Needed)\nGet Your Org\ncurl -s https://api.commune.email/v1/agent/org \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nUpdate Org Name\ncurl -s -X PATCH https://api.commune.email/v1/agent/org \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"My Agent Organization\"}' | jq .\n\nList API Keys\ncurl -s https://api.commune.email/v1/agent/api-keys \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nCreate Scoped API Key (Least-Privilege Pattern)\ncurl -s -X POST https://api.commune.email/v1/agent/api-keys \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"outbound-only\",\n \"permissions\": [\"messages:write\", \"inboxes:read\", \"threads:read\"]\n }' | jq .\n# Raw comm_ key shown ONCE — store immediately in env or secrets manager\n\nRotate a Key (Invalidates Old, Returns New)\ncurl -s -X POST https://api.commune.email/v1/agent/api-keys/key_abc123/rotate \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nRevoke a Key\ncurl -s -X DELETE https://api.commune.email/v1/agent/api-keys/key_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nAgentless Registration (Ed25519 — Zero Human Involvement)\n\nAgents 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.\n\nGenerate Ed25519 Keypair\nfrom cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey\nimport base64\n\nprivate_key = Ed25519PrivateKey.generate()\npub = base64.b64encode(private_key.public_key().public_bytes_raw()).decode()\npriv = base64.b64encode(private_key.private_bytes_raw()).decode()\nprint(\"PUBLIC :\", pub) # 44 chars, ends with =\nprint(\"PRIVATE:\", priv) # store securely\n\nStep 1: Register (Submit Public Key)\ncurl -s -X POST https://api.commune.email/v1/auth/agent-register \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"agentName\": \"My Agent\",\n \"orgName\": \"My Org\",\n \"orgSlug\": \"myorg\",\n \"publicKey\": \"YOUR_BASE64_PUBLIC_KEY==\"\n }' | jq .\n# → { agentSignupToken, challenge, expiresIn: 900 }\n\nStep 2: Sign Challenge + Verify\nimport base64, requests\nfrom cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey\n\npriv_bytes = base64.b64decode(\"YOUR_PRIVATE_KEY\")\nprivate_key = Ed25519PrivateKey.from_private_bytes(priv_bytes)\nchallenge = \"CHALLENGE_FROM_STEP_1\"\nsig = base64.b64encode(private_key.sign(challenge.encode())).decode()\n\nr = requests.post(\"https://api.commune.email/v1/auth/agent-verify\", json={\n \"agentSignupToken\": \"TOKEN_FROM_STEP_1\",\n \"signature\": sig,\n})\nprint(r.json())\n# → { agentId, orgId, inboxEmail: \"myorg@commune.ai\" }\n\n\nAfter verification you can also authenticate every request with Ed25519 instead of API key:\n\nAuthorization: Agent {agentId}:{base64_ed25519_signature_of_request_body}\n\nData Deletion\n\nRequires API key with admin or data:delete permission.\n\nCreate Deletion Request (Preview First, Then Confirm)\n# Preview deletion of all messages in an inbox before a date\ncurl -s -X POST https://api.commune.email/v1/data/deletion-request \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"scope\": \"messages\", \"inbox_id\": \"i_abc123\", \"before\": \"2025-01-01T00:00:00Z\"}' | jq .\n# Returns preview (how many records) + confirmation_token\n\n# Scopes: \"organization\" | \"inbox\" | \"messages\"\n\nConfirm and Execute\ncurl -s -X POST https://api.commune.email/v1/data/deletion-request/req_abc123/confirm \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"confirmation_token\": \"TOKEN_FROM_REQUEST\"}' | jq .\n\nCheck Deletion Status\ncurl -s https://api.commune.email/v1/data/deletion-request/req_abc123 \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nEmail as Persistent Memory\n\nYour Commune inbox persists across every agent session. Patterns for using it as cross-session memory:\n\n# Before reaching out to anyone — check if you've contacted them before\ncurl -s \"https://api.commune.email/v1/search/threads?q=John+Smith+Acme+Corp&inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq '.data[].thread_id'\n\n# Reconstruct the full history of a conversation\ncurl -s \"https://api.commune.email/v1/threads/conv_abc123/messages?order=asc\" \\\n -H \"Authorization: Bearer $KEY\" | jq '.data[] | {direction, content, created_at}'\n\n# Tag threads you need to follow up on\ncurl -s -X POST https://api.commune.email/v1/threads/conv_abc123/tags \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"tags\": [\"follow-up-week-2\"]}' | jq .\n\n# Close resolved threads to keep inbox clean\ncurl -s -X PUT https://api.commune.email/v1/threads/conv_abc123/status \\\n -H \"Authorization: Bearer $KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"status\": \"closed\"}' | jq .\n\n# Find all threads that still need a reply\ncurl -s \"https://api.commune.email/v1/search/threads?q=needs+reply&inbox_id=i_abc123\" \\\n -H \"Authorization: Bearer $KEY\" | jq .\n\nRate Limits\nTier\tPer Hour\tPer Day\nFree\t100 emails\t1,000 emails\nPro\t10,000 emails\t100,000 emails\nEnterprise\tCustom\tCustom\n\nRate limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. 429 Too Many Requests when exceeded.\n\nError Reference\nStatus\tMeaning\n400\tBad request / missing required field\n401\tInvalid or missing API key\n403\tAPI key lacks required permission scope\n404\tResource not found\n409\tConflict — e.g. org slug already taken\n410\tConfirmation token expired\n413\tAttachment storage quota exceeded\n429\tRate limit hit — check Retry-After header\n500\tServer error\n\nAll errors: { \"error\": \"descriptive message\" }\n\nComplete API Reference\nMethod\tEndpoint\tScope Needed\tWhat It Does\nGET\t/v1/domains\tdomains:read\tList all domains\nPOST\t/v1/domains\tdomains:write\tCreate custom domain\nGET\t/v1/domains/:id\tdomains:read\tGet domain details\nPOST\t/v1/domains/:id/verify\tdomains:write\tTrigger DNS check\nGET\t/v1/domains/:id/records\tdomains:read\tGet DNS records to configure\nPOST\t/v1/inboxes\tinboxes:write\tCreate inbox (auto-domain)\nGET\t/v1/inboxes\tinboxes:read\tList all inboxes\nGET\t/v1/domains/:d/inboxes\tinboxes:read\tList inboxes for a domain\nPOST\t/v1/domains/:d/inboxes\tinboxes:write\tCreate inbox under domain\nGET\t/v1/domains/:d/inboxes/:i\tinboxes:read\tGet inbox\nPUT\t/v1/domains/:d/inboxes/:i\tinboxes:write\tUpdate inbox\nDELETE\t/v1/domains/:d/inboxes/:i\tinboxes:write\tDelete inbox\nPUT\t/v1/domains/:d/inboxes/:i/extraction-schema\tinboxes:write\tSet AI extraction schema\nDELETE\t/v1/domains/:d/inboxes/:i/extraction-schema\tinboxes:write\tRemove extraction schema\nGET\t/v1/threads\tthreads:read\tList threads (paginated)\nGET\t/v1/threads/:id/messages\tthreads:read\tGet full conversation\nGET\t/v1/threads/:id/metadata\tthreads:read\tGet tags/status/assignee\nPUT\t/v1/threads/:id/status\tthreads:write\tSet status\nPOST\t/v1/threads/:id/tags\tthreads:write\tAdd tags\nDELETE\t/v1/threads/:id/tags\tthreads:write\tRemove tags\nPUT\t/v1/threads/:id/assign\tthreads:write\tAssign/unassign thread\nPOST\t/v1/messages/send\tmessages:write\tSend email\nGET\t/v1/messages\tmessages:read\tList messages (filter required)\nGET\t/v1/search/threads\tthreads:read\tSemantic/vector search\nPOST\t/v1/attachments/upload\tattachments:write\tUpload file (base64)\nGET\t/v1/attachments/:id\tattachments:read\tGet attachment metadata\nGET\t/v1/attachments/:id/url\tattachments:read\tGet signed download URL\nGET\t/v1/delivery/metrics\tmessages:read\tDelivery stats\nGET\t/v1/delivery/events\tmessages:read\tPer-message event log\nGET\t/v1/delivery/suppressions\tmessages:read\tBounced/complained addresses\nGET\t/v1/webhooks/deliveries\tmessages:read\tList webhook deliveries\nGET\t/v1/webhooks/deliveries/:id\tmessages:read\tFull delivery detail\nPOST\t/v1/webhooks/deliveries/:id/retry\tmessages:write\tRetry dead delivery\nGET\t/v1/webhooks/health\tmessages:read\tPer-endpoint health stats\nPOST\t/v1/dmarc/reports\tdomains:write\tSubmit DMARC XML report\nGET\t/v1/dmarc/reports\tdomains:read\tList DMARC reports\nGET\t/v1/dmarc/summary\tdomains:read\tDMARC pass/fail summary\nGET\t/v1/agent/org\t—\tGet own org\nPATCH\t/v1/agent/org\t—\tUpdate org name\nGET\t/v1/agent/api-keys\t—\tList API keys\nPOST\t/v1/agent/api-keys\t—\tCreate scoped API key\nDELETE\t/v1/agent/api-keys/:id\t—\tRevoke key\nPOST\t/v1/agent/api-keys/:id/rotate\t—\tRotate key\nPOST\t/v1/auth/agent-register\tpublic\tRegister (Ed25519 public key)\nPOST\t/v1/auth/agent-verify\tpublic\tVerify challenge → activate\nPOST\t/v1/data/deletion-request\tadmin/data:delete\tCreate deletion request\nPOST\t/v1/data/deletion-request/:id/confirm\tadmin/data:delete\tExecute deletion\nGET\t/v1/data/deletion-request/:id\tadmin/data:delete\tCheck deletion status" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/shanjairaj7/commune", "publisherUrl": "https://clawhub.ai/shanjairaj7/commune", "owner": "shanjairaj7", "version": "1.0.1", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/commune", "downloadUrl": "https://openagent3.xyz/downloads/commune", "agentUrl": "https://openagent3.xyz/skills/commune/agent", "manifestUrl": "https://openagent3.xyz/skills/commune/agent.json", "briefUrl": "https://openagent3.xyz/skills/commune/agent.md" } }