e2a — email for AI agents

Move a message to the trash. It disappears from lists, threads, and reply targets, but stays restorable with `restore_message` until the trash-retention window expires (30 days by default). Permanent deletion ("delete forever") is deliberately NOT exposed here — use the REST API/SDK for that. A message held for review cannot be deleted (`message_held`) — resolve it in the review queue first. Requires `confirm: true` — set it explicitly to acknowledge the destructive action.

Remove only this agent's outreach state. Account contact identity and suppression survive; this does not restore sendability.

Remove an address from the account-wide suppression list so sends to it succeed again. Only do this when the address is known to be deliverable — removing a genuinely bouncing or complaining recipient hurts sender reputation. Requires confirm:true so an LLM cannot restore sendability on ambiguous context. Account scope only.

Permanently delete a stored template. In-flight sends are unaffected (rendering happens at send time), but future sends referencing its id or alias will fail. Requires confirm:true so an LLM cannot delete on ambiguous context. Beta: templates are unstable — their shape may change before they are declared stable.

Permanently remove a webhook subscription. CASCADES to pending delivery rows. Requires confirm:true so an LLM cannot delete on ambiguous context.

Forward a message the agent has received OR one it sent to one or more new recipients. The server auto-prepends a Gmail-style header block (From/Date/Subject/To/Cc) and the original body to whatever optional comment you pass in `text`/`html`, **and carries over the original message's attachments by default** — you do NOT need to re-fetch them via `get_attachment`. Anything you pass in `attachments[]` is added on top of the originals. **Unlike `reply_to_message`, a forward is a NEW thread** — no In-Reply-To / References headers are emitted, so the recipient sees a fresh conversation. Use this w…

Beta: delivery counter metrics across EVERY agent on the account, on the same counters and rate denominators as get_agent_metrics — so an account total and the per-agent numbers under it cannot disagree. Use this for an account-level health check; use get_agent_metrics to drill into one inbox. Set group_by:'agent' to also receive a per-agent breakdown in `agents`, busiest first — it is capped at 200 agents and sets `agents_truncated` when it cuts, while the account totals stay complete either way. Set bucket:'day' to also receive `buckets`: one entry per UTC calendar day, gap-filled so a silen…

Fetch a single agent by its email address — identity + status (name, domain, verification, created_at). The screening/protection config (gate, scan, holds) is NOT here: it is account-only and lives on `get_protection`. Use to inspect or confirm one agent without listing every agent. Read-only.

Beta: delivery counter metrics for ONE agent, aggregated from the message lifecycle ledger — how much mail this agent got accepted, submitted, delivered, bounced, complained about, or had blocked by a suppression, plus inbound DMARC results and human-review outcomes. Use this to check an inbox's own sending health before or after a campaign. Messages join the window by their own send time, not by when each observation landed. Bounce and complaint feedback keeps arriving for up to 72 hours, so treat the most recent days as provisional rather than final. Defaults to the last 30 days; the window …

Returns one attachment's metadata plus a short-lived `download_url` (+ `expires_at`) — fetch the bytes out of band so binary content never streams through your context (no size limit). `attachment_index` is the 0-based `attachments[].index` from `get_message`. Pass `inline: true` to ALSO get base64 `data` for small attachments (≤256 KB; larger inline requests error) — use this only when you must re-attach the bytes (e.g. forwarding a small file via `send_message`'s `attachments[]`); otherwise hand the `download_url` to whatever needs the file.

DEPRECATED — use `get_attachment` with `inline: true` instead. Returns one attachment's metadata plus its bytes as base64 `data`, always inline. It exists only for MCP clients pinned to the old schema, and it is strictly weaker than `get_attachment`: it cannot return a short-lived `download_url`, so every fetch streams the whole file through your context, and attachments over the 256 KB inline limit fail outright rather than falling back to a URL. Prefer `get_attachment` and hand the `download_url` to whatever needs the file.

Fetch one account-scoped contact by address and return its `etag`. Pass that validator as `if_match` when updating to reject stale edits. Account scope only.

Returns the full application conversation group — aggregate counts, the participants union (sender + recipient + to + cc + bcc across members), the labels union, and every live member message in chronological order (oldest first). This groups by `conversation_id`, which is independent of email thread topology. Returns a not-found error when no live messages exist for `(agent, conversation_id)`. Use this after `list_conversations` (or whenever you have a `conversation_id` from an inbound/outbound payload) to read the full group.

Fetch a single domain by name. This is the poll target after `verify_domain`: it surfaces `capabilities` — `{inbound, outbound}`, the per-axis rollup of what the domain can actually do, and the field to prefer — alongside the equivalent legacy fields `verified` (inbound ownership) and `sending_status` (none/pending/verified/failed — the async SES sending identity that lets agents on this domain send as their own address), plus `sending_error` and `dns_records` (one purpose-tagged array — each record has `type`/`name`/`value`/`purpose`/`status`, covering ownership, inbound MX, DKIM, and the MAI…

Fetch a single event by id. The response includes the full envelope payload AND a `delivery_status` block showing how many of the matched webhooks have delivered/pending/failed. Use this to triage "did this specific event reach my receiver?" Returns an error with status 410 if the event has passed the 30-day retention boundary (replay is no longer possible).

Use after `list_messages` to read one inbound or outbound message in full; for outbound messages, this is also how you poll a send's terminal outcome. Returns text + HTML, direction, labels, delivery/review lifecycle, suspicious-message flags and protection findings, header_from, envelope_from, verified_domain, SPF/DKIM/DMARC evidence, conversation id, and attachment metadata. `truncated:true` means the inbound parser clipped the decoded body. A non-null verified_domain means DMARC passed for the RFC 5322 From domain; it does not authenticate the mailbox local part, a person, or message conten…

Beta: returns the ordered transitions e2a observed for one persisted inbound or outbound message; the lifecycle contract may change before it is declared stable. SMTP acceptance, upstream submission, provider delivery feedback, and complaint feedback remain distinct; this does not claim inbox placement. **Cursor-paginated:** returns one page in `transitions` plus `next_cursor` only when more pages remain; pass it back as `cursor` to continue, and stop when it is absent.

Fetch one agent/contact outreach record, including reply facts, suppression, and an `etag`. Pass the validator as `if_match` when updating to reject stale agent loops.

DEPRECATED: use `get_review`. This account-only compatibility alias accepts the historical pending message ID and returns canonical review detail.

Read an agent's protection posture: the inbound/outbound trust gate (policy + allowlist + action), the content-scan sensitivity, and the hold-queue mechanism. BETA — the shape may change. Account scope only: an agent-scoped credential cannot read its own protection config.

Account scope only. Fetch the full detail of one inbound screening hold or outbound send hold, including subject, recipients, body, attachments, and screening context. A review's `id` is the held message's id (msg_…) and is the same ID accepted by `approve_review` and `reject_review`. Body content is only present while the message is `pending_review`; after a terminal transition the server scrubs it. Like `get_message`, raw MIME (`raw_message`) and attachment bytes are intentionally omitted to protect context — attachments surface as metadata only. Webhook delivery diagnostics (`webhook_error`…

Read this account's most recent request for external sending access and its review `state` (`pending`, `approved`, `declined`; open set — treat unknown values as not approved). Fails with `not_found` (404) when the account has never filed one, and `not_implemented` (501) when the deployment does not restrict external sending at all. The decision is made by an operator and emailed to the account owner — it does not arrive through this tool or any webhook; check back later with `get_sending_access_request`. `whoami`'s `sending_access.available_unlocks` explains what can lift the restriction on t…

Fetch one starter template by alias, including its full plain-text and HTML body sources and its variables (each with a realistic example value usable as test_data). Starters are read-only masters: to customize one, copy it with `create_template` {from_starter: alias} and edit the copy. Variables with raw:true are {{{…_html}}} fragment slots — the caller supplies pre-rendered HTML and MUST escape user content in it. For the approval-request starter: approve_url/reject_url MUST point to CONFIRMATION PAGES that require an explicit click (or auth) to act — NEVER state-changing GET endpoints. Emai…

Fetch one stored template by id (tmpl_…), including its subject/text/html sources. Templates copied from a starter also carry fromStarterAlias/fromStarterVersion (read-only provenance). Beta: templates are unstable — their shape may change before they are declared stable.

Fetch a single webhook by id. signing_secret is omitted — use rotate_webhook_secret if the secret was lost.

Import up to 1000 already-parsed rows. This NEVER sends email. Optionally set `agent_email` to enroll every valid row atomically; `stage` initializes only new outreach records. Existing engagement state and all suppression survive. Account scope only. Parse CSV at the client edge.

List recipient addresses blocked only for this exact sending agent (unsubscribes and manual blocks). Cursor-paginated: returns `suppressions` and optional `next_cursor`. Account scope only.

List the agent inboxes owned by the authenticated account, newest first. Set `deleted:true` to list the 30-day trash instead of live agents. Account scope only. **Cursor-paginated:** returns one page in `agents` plus a `next_cursor` when more remain — pass it back as `cursor` for the next page. Read-only.

Returns the account's API keys — metadata only: `id`, `name`, non-secret `keyPrefix`, `scope`, bound `agentEmail` (agent-scoped keys only), and created/last-used/expiry timestamps. The secret is shown ONCE at creation and can never be retrieved again; a lost key must be deleted and re-minted. **Cursor-paginated:** returns one page in `api_keys` plus a `next_cursor` when more remain — pass it back as `cursor` for the next page. Read-only; cheap.

List account-scoped contact identity. Account scope only. This is identity/provenance, not an outreach sequence. Cursor-paginated: returns `contacts` and optional `next_cursor`.

Lists the agent's application conversations — groups of messages sharing a `conversation_id` — one row per group, sorted by most recent activity. `conversation_id` is independent of email thread topology. Each row carries `message_count`, `inbound_count`, `outbound_count`, `has_unread`, and the latest message's subject + sender so you can render grouped activity without loading every message. **Cursor-paginated:** returns one page in `conversations` plus a `next_cursor` when more remain — pass it back as `cursor` for the next page. To read a single conversation's messages, call `get_conversati…

List the custom mail domains registered under the authenticated user, newest first, with verification status (verified / pending DNS / failed) and the verification token for each. Useful to discover which domains can already send/receive mail and which still need DNS records to be added. **Cursor-paginated:** returns one page in `domains` plus a `next_cursor` when more remain — pass it back as `cursor` for the next page. Read-only; cheap to call.

List the durable webhook event log in reverse-chronological order. Useful for reconciliation ("did our webhook receiver see this event?") and for debugging delivery state. Events past the 30-day retention boundary are not returned. **Cursor-paginated:** returns one page in `events` plus a `next_cursor` when more remain — pass it back as `cursor` to walk further back. Returns each event's `data` payload plus a `delivery_status` summary of how many subscribers have received it.

List the agent's messages, newest first by default. Use `direction` to pick the folder: `inbound` (the Inbox — received mail, the default), `outbound` (the Sent folder — mail this agent sent, including held drafts), or `all` (both). Filter received mail by `read_status` (unread/read/all; default unread — applies to inbound only; sent mail has no read-state). **Cursor-paginated:** returns one page in `messages` plus a `next_cursor` when more remain — pass it back as `cursor` for the next page (keep the same filters + sort). Pass `sort: "asc"` for FIFO order (oldest first) to drain in arrival or…

List the contacts this agent is working. For a safe follow-up pull use `replied:false`, `suppressed:false`, `next_action_before:now`, and `last_outbound_before:<stale cutoff>` together. Never-contacted rows are included by the last-outbound filter. e2a stores state and wakes the agent; it NEVER composes or sends a follow-up. Cursor-paginated.

DEPRECATED: use `list_reviews`. This account-only compatibility alias walks the unified review queue and preserves the historical messages response envelope.

Account scope only. Use when the account owner asks what's awaiting approval, or after a send returned `pending_review`. Lists inbound screening holds and outbound send holds across every inbox in the authenticated account, sorted by soonest-expiring first. Body content is summary-only; call `get_review` with the review's `id` for full detail, then use that same ID with `approve_review` or `reject_review`. **Cursor-paginated:** returns one page in `reviews` plus `next_cursor` only when more remain; pass it back as `cursor`. The `email.review_requested` webhook is an additional push notificatio…

List the pre-built starter templates shipped with the deployment (welcome, verify-code, password-reset, receipt, agent-status, daily-digest, approval-request), with each one's variables — name, required?, raw?, description, example. Catalog metadata only; `get_starter_template` adds the full body sources. Copy one into the account's library with `create_template`'s from_starter, then send with template_alias. Variables marked raw:true are {{{…_html}}} fragment slots — HTML-escape any user content you splice into them. **Cursor-paginated:** returns one page in `starter_templates` plus a `next_c…

List the account-wide suppression list: recipient addresses e2a will refuse to send to from ANY agent, auto-added on a hard bounce or complaint. Sends to them fail with recipient_suppressed. Cursor-paginated: returns `suppressions` and optional `next_cursor`. Account scope only.

List the account's stored email templates, newest first — summary rows (id, name, alias, subject, timestamps); `get_template` returns the full body sources. Use a template on send via `send_message`'s template_id or template_alias. **Cursor-paginated:** returns one page in `templates` plus a `next_cursor` when more remain — pass it back as `cursor` for the next page. Read-only; cheap. Beta: templates are unstable — their shape may change before they are declared stable.

Returns the delivery rows for one webhook, newest first. Each row includes status (pending|delivered|failed), attempts, last_error, last_status_code, and timestamps. The way to debug why a subscriber is missing events, or to check the outcome of a `test_webhook` call. **Cursor-paginated:** returns one page in `deliveries` plus a `next_cursor` when more remain — pass it back as `cursor` (keep the same `status` filter). Read-only. Distinct from `list_events` (the account-wide event log); this is the per-webhook delivery ledger.

Returns the webhook subscribers owned by the authenticated user, newest first, enabled + disabled, with their event subscriptions, filters, and last-delivered timestamp. signing_secret is omitted (it is only ever returned on create + rotate). **Cursor-paginated:** returns one page in `webhooks` plus a `next_cursor` when more remain — pass it back as `cursor` for the next page. Read-only; cheap.

Re-fire a previously-emitted event to a webhook. Pass `webhook_id` to target one subscriber. Omit `webhook_id` to fan out to every webhook that originally matched the event (per the snapshot at fan-out time; does NOT re-evaluate against the current subscriber set, by design). **Important:** the replay uses the SAME envelope id as the original delivery. Customer-side receivers that dedupe on event id will discard the replay as already-processed — replay is recovery, not re-delivery. Use this for outage recovery, not for "send this event twice on purpose."

Use to start the custom-domain flow. **This is step 1 of an asynchronous two-step process**: this tool returns the MX + TXT records the user must publish on their DNS provider; it does NOT make the domain live. Step 2 is `verify_domain` — but only AFTER the records are published AND DNS propagation has completed (typically minutes, occasionally hours). Do not call `verify_domain` immediately, and do not promise the user the domain works yet. **Composition tip**: if a DNS-provider MCP (Cloudflare, Route 53, NS1, …) is loaded in the same host, hand the returned records to its `create_dns_record`…

DEPRECATED: use `reject_review`. This account-only compatibility alias preserves message_id and the optional rejection reason.

DEPRECATED: use `reject_review`. This account-only compatibility alias preserves message_id and the optional rejection reason.

Reject a message held in `pending_review` (a review). The server branches on direction: an **outbound** hold is discarded without sending and retained with its body and attachments, while an **inbound** screening hold is dropped so it never reaches the agent and its raw payload remains retained and hidden for forensics. The optional `reason` is stored for audit. Returns 409 if the message is no longer pending.

Use whenever you're responding to a message you can see — preserves the In-Reply-To and References headers so the reply joins the original email thread instead of starting a new one. Works on both a message the agent RECEIVED (replies to its sender) and a message the agent SENT (continues the thread to its original recipients, i.e. a Gmail-style follow-up on your own message). Prefer this over `send_message` for any in-thread response; thread fragmentation (broken conversation view in the recipient's mail client) is the most visible symptom of using `send_message` by mistake. Pass `reply_all: …

Use when a send failed with `external_sending_not_enabled` (or `whoami`'s `sending_access` shows the account is restricted) and the account legitimately needs to email external recipients. Files ONE request for an operator to review; filing never grants access by itself. Call it ONCE: while a request is pending, calling again just returns the same pending request — do not retry or re-file. Do NOT retry on `rate_limited` (429; at most 3 requests per 30 days per account), `conflict` (409: the account is not restricted — already approved, or the control does not apply to it — so there is nothing …

Restore an agent that was soft-deleted within the 30-day trash window, including its messages and configuration. Scheduled messages restored before `scheduled_at` re-arm; at/after `scheduled_at` they return live as failed with submission canceled. Account scope only. Returns the restored agent; a live agent returns `not_in_trash`, while an agent already claimed by permanent deletion returns `purge_in_progress` and cannot be restored.

Restore a soft-deleted message before its trash-retention window expires. A scheduled message restored before `scheduled_at` re-arms; at/after `scheduled_at` it returns live as failed with submission canceled. Returns the restored message; a live message returns `not_in_trash`.

Generate a new signing_secret and move the current one into a 24h grace window during which the worker dual-signs each delivery (two v1= entries on X-E2A-Signature). The new plaintext is returned ONCE — every subsequent list/get scrubs it. Use when the previous secret was leaked or rotated by policy.

DEPRECATED — use `send_message` instead. Sends a new email from the agent's inbox to one or more recipients, identical to `send_message` except that it keeps the historical field names (`body`/`html_body`/`agent_email` rather than `text`/`html`/`email`). It exists only for MCP clients pinned to the old schema and gains no new features: templates and scheduled sending are unavailable here. Like `send_message`, it starts a NEW thread — use `reply_to_message` to respond to a message you can see. **`accepted` and `pending_review` are both success, not failure — do NOT re-send.** `accepted` means t…

Use when starting a NEW email thread to a fresh recipient. To respond to a message you can see in `list_messages`, use `reply_to_message` instead — it preserves the In-Reply-To / References headers so the reply lands in the same thread, which this tool deliberately does not do. Attach files via `attachments`; pass base64 strings produced by other tools (e.g. `get_attachment`) verbatim — don't hand-encode raw text. **`accepted`, `scheduled`, and `pending_review` are all success, not failure — do NOT re-send.** `{ status: "accepted", message_id: ... }` means the send was durably persisted and qu…

Enroll a contact or update agent-owned stage, next action, and metadata. Omitted fields remain unchanged. Pass `if_match` from get_outreach_contact to reject a stale update; conditional writes never enroll a missing contact. This NEVER sends email; `next_action_at` schedules `contact.due` for configured webhooks. A deployed agent runtime can consume that event; it does not launch a local coding-agent session over MCP or WebSocket.

Schedules a one-off delivery to the webhook with a synthetic envelope, bypassing filter matching. Returns the delivery_id; inspect the outcome (status/attempts/last_error) via `list_webhook_deliveries`. Returns an error if the webhook is disabled. Cheap and safe — the synthetic event does not touch real inbound or review state.

Update an agent's display name (a UI label; the agent's identity is its email). The screening/protection config (gate, scan, holds) is NOT here — use `update_protection`.

Partially update display name or metadata. Address and provenance are immutable. Pass `if_match` from get_contact to reject a stale write. Account scope only.

Apply a labels delta — `add_labels` and/or `remove_labels`. Labels are lowercase strings drawn from `[a-z0-9:_-]+`, capped at 64 chars each; the `e2a:` prefix is reserved for server-applied system labels and rejected on writes. A label appearing in both lists is removed (remove wins). Per-request cap is 50 entries per list; per-message cap is 100 total labels. The response includes the post-update label set so you can echo back to the user without a follow-up read. Use this when the user wants to categorize a message (e.g. `add: urgent`) or clear a tag (`remove: follow-up`).

Set an agent's protection posture. Read-modify-write: only the fields you pass change; the rest keep their current value. Inbound allowlist/domain gates first require DMARC pass, then match the aligned RFC 5322 From address. Outbound policy semantics: open matches every recipient; allowlist matches exact addresses in outbound_gate_allowlist; domain matches recipients on the agent's own domain. The outbound gate action applies when any recipient does not match. To require human review for every outbound message, set outbound_gate_policy=allowlist, outbound_gate_allowlist=[], outbound_gate_actio…

Partial update of a stored template. Fields you do NOT pass are left unchanged; changed template parts are re-parsed (bad syntax rejects the update). Set alias or html to "" to clear them. Sends already in flight are unaffected — rendering happens at send time, so future sends pick up the new source. Template syntax (flat Mustache subset): {{var}} interpolates (HTML-escaped in html only; raw in subject/text), {{{var}}} interpolates raw everywhere; dot paths reach nested template_data ({{user.name}}). NO loops/sections/partials/comments — {{#…}}, {{/…}}, {{^…}}, {{>…}}, {{!…}} are parse errors.…

Partial update. Fields you do NOT pass are left unchanged. url / events / filters are full-replace when present (no array merge). Use enabled:false to pause delivery without losing config; enabled:true re-enables (subject to a 5-min cooldown after auto-disable).

Dry-run template source WITHOUT persisting anything: returns per-part parse errors, a rendered preview against test_data (present only when valid), and suggestedData — a placeholder value for every variable the source references, nested along dot paths (a ready-made starting point for template_data). Use this before `create_template` to catch syntax errors, and to spot silent blanks: a missing variable renders as empty string, so preview with realistic test_data and check the output. Template syntax (flat Mustache subset): {{var}} interpolates (HTML-escaped in html only; raw in subject/text), …

Use as step 2 of the custom-domain flow, AFTER `register_domain` returned records AND the user (or a DNS MCP) published them AND DNS has had time to propagate (minutes to hours). Probes DNS for the issued MX + TXT records and flips the domain's `verified` bit on success. Idempotent — safe to retry as propagation completes. If `verified: false` comes back, the response includes the resolved-record state for diagnostics; surface that to the user rather than retrying in a tight loop. **A `dkim: "mismatch"` result is distinct from `"missing"`**: the DKIM record IS published but its key doesn't mat…

Use first when starting work on e2a to learn WHO you are: the authenticated user (email), the credential's scope (`account` or `agent`), and your plan + usage limits. When present, `daily_limit` reports today's external-recipient allowance, usage (including pending sends), and UTC reset time; shared-identity usage is a subset capped by `shared_limit`. Internal mail to own live agents and the verified owner mailbox does not consume it. For an agent-scoped credential it also returns `agent_email` — the single agent that credential IS. Account-scoped credentials own many agents; discover them wit…