commune-email

Skill: Commune Email

What I Can Do

I give you a real email inbox and let you send, receive, search, and manage email threads programmatically via the Commune API. Every inbox I create is RFC 5322 compliant — replies thread correctly in any email client, including Gmail, Apple Mail, and Outlook.

Authentication

Requires COMMUNE_API_KEY environment variable. Get one at commune.email.

Base URL: https://api.commune.email
Auth header: Authorization: Bearer $COMMUNE_API_KEY
Content-Type: application/json

My Inbox Address

COMMUNE_INBOX_ADDRESS — set this environment variable to your full inbox address after creation (e.g. [email protected]). Also set COMMUNE_INBOX_ID to the inbox's ID string.

---

Core Operations

Create Inbox

POST /v1/inboxes
Body: { "localPart": "assistant" }
Response: { "id": "inbox_xxx", "address": "[email protected]" }

Save the returned id as COMMUNE_INBOX_ID and address as COMMUNE_INBOX_ADDRESS.

---

List Email Threads

GET /v1/threads?inbox_id=INBOX_ID&limit=20

Response shape:

{
  "data": [
    {
      "thread_id": "thread_xxx",
      "subject": "Re: Contract draft",
      "last_direction": "inbound",
      "message_count": 3,
      "last_message_at": "2026-02-28T10:00:00Z"
    }
  ]
}

Important: last_direction: "inbound" means the last message came from the other person — this thread is waiting for a reply. last_direction: "outbound" means you replied last.

---

Read a Thread

GET /v1/threads/THREAD_ID/messages

Returns an array of messages with:

• direction: "inbound" or "outbound"
• content: the message body text
• participants: array of { role: "sender"|"recipient", identity: "[email protected]" }
• metadata.subject: the email subject

Always read the full thread before replying — context matters.

---

Send Email (New Thread)

POST /v1/messages/send
Body: {
  "to": "[email protected]",
  "subject": "Meeting notes from today",
  "text": "Hi Sarah, here are the notes...",
  "inboxId": "INBOX_ID"
}