# E2a > Use when operating an already-connected e2a inbox over MCP: reading, composing, sending, replying, forwarding, handling attachments, managing contacts/outreach, scheduling mail, or using templates. Teaches correct threading, conversation correlation, concise multipart composition, and accepted/pending-review no-retry behavior. - Skill: `tokencanopy/e2a` (Agent Skill) - Install (CLI): `npx skillmds@latest add tokencanopy/e2a` - Raw SKILL.md: https://api.skillmd.com/api/skills/tokencanopy/e2a/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tokencanopy (https://skillmd.com/u/tokencanopy) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tokencanopy/e2a --- # Using e2a e2a is the open-source email API for applications and AI agents. This operate-well skill focuses on agent-owned inboxes: it gives an agent a real two-way address (`agent@agents.localhost` or `agent@example.com`), evaluates SPF, DKIM, and DMARC as structured evidence about the From domain, and threads conversations. That evidence does not prove a person, mailbox, or message content. ## How this fits This file is the **operate-well manual** — the mental model and gotchas. It assumes you're already connected over MCP (the tools appear as `mcp__e2a__*`). - **Connect, authorize, select/create an inbox, or configure a custom domain** → use `e2a-setup`. - **Add e2a sending, receiving, SDK, REST, or webhook code to an application** → use `e2a-integrate`. - **Investigate a failing connection, inbox, domain, webhook, or delivery** → use `e2a-doctor`. - **Exact, current tool signatures** → call `tools/list` (authoritative). The mental model below holds regardless of surface. Tool descriptions teach the precise per-tool contract; this file teaches the model the descriptions assume. ## The mental model Six load-bearing facts. Internalize these before you start calling tools. 1. **An agent is an email address.** `support-bot@agents.localhost` is an agent. When you send mail, the recipient sees a message FROM that address — not from "the user." When you list messages, you are reading the agent's own inbox, not the user's personal mail. You are not a secretary; you are the mailbox owner. 2. **Replies preserve threads; new sends do not.** `reply_to_message` carries the `In-Reply-To` and `References` headers from the original message, so the response lands in the same email thread. A fresh `send_message` creates a new thread every time. If a user (or an inbound message) is asking you to respond to something specific, reply with the original `message_id` — even when you could synthesize an equivalent body as a new send. Thread fragmentation is the #1 visible symptom of getting this wrong. **Email topology and application correlation do not share a key.** Gmail, Outlook, and Apple Mail thread on RFC `Message-ID` / `In-Reply-To` / `References` plus a **stable `Subject`**. `reply_to_message` sets those headers correctly. `conversation_id`, which backs `list_conversations` / `get_conversation`, is caller-owned workflow correlation: a fresh `send_message` with the same value is still a separate email thread, while a reply with a changed value stays in its parent's email thread. REST message reads may expose optional beta `thread_id`, a server-owned mailbox-local topology identity, but MCP deliberately omits it and provides no thread filter or endpoint. Within one ongoing exchange: reply, and keep the subject stable. **Bind email to the agent runtime's conversation.** When received mail starts or resumes a coding-agent task, establish the runtime thread before replying. If the inbound `conversation_id` matches a binding your integration previously stored, resume that internal thread; otherwise create a new internal thread. When the runtime exposes a stable, non-sensitive thread/session ID, pass it as `conversation_id` on the first reply and reuse it on later sends and replies. If its native ID is sensitive or does not meet e2a's 200-character, no-CR/LF constraint, store and pass an opaque alias instead. This keeps e2a's application-conversation view aligned with the agent's memory, but it does **not** replace replying with the original `message_id`, which is what preserves the recipient's email-client thread. Treat `conversation_id` as correlation data, never authorization. 3. **`pending_review` is an accepted outcome, not a retry signal.** A send can return `{ status: "pending_review", message_id: "msg_..." }`. The server accepted the message but did not dispatch it. Do not retry: another call can create a duplicate. Report the status and message ID to the user, then stop. 4. **Account-scoped sessions need an explicit inbox.** `whoami` tells you the credential scope and returns `agent_email` only for an agent-scoped credential. An account-scoped MCP session never guesses a default, even when the account has one inbox: enumerate once with `list_agents`, then pass the tool's `email` field explicitly. Don't guess or pick at random; use the user's stated context when it clearly identifies an inbox. 5. **Most users don't need a custom domain — default to the shared one.** Every account can create agents on the shared `agents.e2a.dev` domain with zero DNS setup: call `create_agent` with the full address (for example, `support-bot@agents.e2a.dev`), and it is live immediately. This is the right default for onboarding and for anyone who doesn't already **own** a domain. Only reach for a custom domain when the user explicitly owns a domain and wants branded addresses — if they don't own one, stay on `agents.e2a.dev` and skip the domain flow entirely. Don't send a user who just wants to get started down the DNS dance. 6. **Custom domains are a two-step async dance.** `register_domain` returns DNS records (MX + TXT) to publish — it does NOT make the domain live. The user (or a DNS-provider MCP, such as [Cloudflare MCP](https://github.com/cloudflare/mcp), if one is loaded) must add those records out-of-band, wait for DNS propagation (minutes to hours), then `verify_domain`. Verification is idempotent and safe to retry. Until verification succeeds, the domain cannot send or receive mail. Don't promise the user their domain works the moment registration returns. ## Common workflows ### Optional: require human review for every outbound email Only when the user asks for every outbound email to require human review, configure this policy. After selecting the inbox, call `update_protection` for that inbox with: ```json { "outbound_gate_policy": "allowlist", "outbound_gate_allowlist": [], "outbound_gate_action": "review", "holds_on_expiry": "reject" } ``` The empty allowlist makes every recipient a gate non-match, `review` holds each non-match for a human, and `reject` prevents an unreviewed message from being sent when its hold expires. Do not use `open` with `review` for this outcome: `open` matches every recipient, so the recipient gate holds nothing. This is opt-in; never enable it merely because an inbox was created. ### Triage the inbox 1. List unread messages with `list_messages` (defaults to `read_status: unread`). 2. Read one fully with `get_message` (the `message_id`). 3. Create or resume the coding agent's internal thread. If the runtime exposes a safe stable thread/session ID, pass it as `conversation_id`. 4. Reply in-thread with `reply_to_message` and the original `message_id`; reuse the bound `conversation_id` on later replies. For attachment bytes, use `get_attachment` with a 0-based index. It returns the attachment's metadata plus a short-lived `download_url`; pass `inline: true` to get base64 `data` inline for small files. Indexes are stable within a message. ### Manage contacts and outreach (beta) Contacts are durable account-level identity; outreach is one inbox's state for working that contact. e2a stores the state and derives real send/reply facts, but it never writes or sends a follow-up on its own. 1. Import and optionally enroll with `import_contacts`. Pass already-parsed rows, an explicit `agent_email`, and an optional initial `stage`. Import never sends email. Account scope is required for the account-wide import. 2. When the user asks to work the queue, call `list_outreach_contacts` with `replied=false`, `suppressed=false`, `next_action_before=`, and `last_outbound_before=`. The last filter is the duplicate-send safety net when a prior send succeeded but the later state update failed. 3. Start first contact with `send_message`. Continue an existing thread with `reply_to_message` and a message from that thread; a new send fragments the recipient's inbox even if `conversation_id` is reused. 4. After an accepted send, update the caller-owned `stage` and `next_action_at` with `set_outreach_contact`. e2a updates reply status, activity timestamps, counts, and the latest conversation from real mail. Preserve the normal `pending_review` no-retry rule. `next_action_at` is not a scheduled send — it sends nothing. It makes the row available to the due query and emits `contact.due`, a notification. Only a deployed webhook receiver can use that event to wake an agent runtime; it does not launch a local coding-agent session over MCP or WebSocket. Claude Code and similar interactive clients work the queue when the user starts or resumes them. If you want e2a itself to submit an already-composed message at a future time, that is the separate beta `send_at` scheduled-send capability (see "Schedule a send for later" below) — do not conflate the two: `send_at` delivers without anyone waking up, `next_action_at` only flags that someone should. ### Compose before sending Write for a busy recipient scanning on a phone. 1. Lead with the outcome, decision, request, or blocker in one sentence. 2. Include only information that changes understanding or action. 3. Use short labeled sections and bullets when the message has more than one point. 4. Put any required decision or action in its own line. 5. Link the primary artifact once; leave exhaustive logs and test inventories in the linked artifact. For a status update, prefer this shape: ```text Outcome: Shipped - - Verified - Blocker / decision - Next: Artifact: ``` Omit empty sections. Default to 120–180 words and no more than five bullets. Use one idea per bullet and one or two sentences per paragraph. Do not narrate the work chronologically, repeat the same status in prose and bullets, or paste implementation details that do not affect readiness, risk, or a decision. Always provide a complete plain-text body. Also provide an equivalent `html` body when the email has sections, bullets, or links; plain text alone is fine for a one- or two-sentence reply. Keep HTML email-safe: use simple `

`, ``, `