E2a

Using e2a

<!-- version: 29 -->

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, 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:

{
  "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=<now>, and last_outbound_before=<stale cutoff>. 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:

Outcome: <one sentence>

Shipped
- <material change>
- <material change>

Verified
- <highest-signal evidence>

Blocker / decision
- <specific ask or owner>

Next: <one sentence>

Artifact: <URL>

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 <p>, <strong>, <ul>, <li>, and <a> elements; avoid scripts, images, tables, custom fonts, and elaborate CSS. Make links descriptive and clickable. Preserve the same facts, order, and links in both bodies.

Before sending, verify that the first sentence states what changed or what is needed, any blocker or decision is unmistakable, the message can be understood in ten seconds, and the plain-text and HTML bodies agree.