Docs

Email for Agents documentation

Give an AI agent its own email address, then let it read, draft and send through a scoped credential you can revoke. This page is the shared reference the rest of the documentation builds on; every number below is read out of the implementation, not the marketing copy.

Last reviewed September 21, 2026 against the implementation in this repository.

If you have not created an inbox yet, start with the two-minute quickstart. If you are deciding whether to build on the REST API or connect over MCP, the agent email API overview covers the product surface and MCP or API key for agent email compares the two credential models side by side.

Surfaces and base URLs

The API version string is 2026-09-19. It appears on every event record and on every webhook body, so a consumer can branch on it rather than guessing from the payload shape.

Authenticating a request

There are two machine credentials and they are not interchangeable. Which one you hold decides which surface you may call.

Project-scoped API keys

Create a key in Access. The plaintext is shown once. Its shape is efa_test_<8 hex>_<43 base64url characters> for a test project and efa_live_… for a live one, so the environment is legible in a log line without resolving the key. Send it as Authorization: Bearer efa_live_…. Only the digest is stored, which is why a lost key must be replaced rather than recovered. Revoke one with POST /v1/keys/{key_id}/revoke.

Connection grants for MCP

MCP clients authenticate with an OAuth connection grant, obtained through a browser consent step in which a human picks the specific inboxes and the permission preset. An efa_ API key presented at /mcp is rejected, and so is a console session token: only a principal of type connection may invoke MCP tools. That is deliberate, not a gap — an MCP client is software a human authorised for named inboxes, and the grant carries that authorisation. The server identifies itself as email-for-agents-mcp 1.0.0 and negotiates protocol versions 2025-11-25, 2025-06-18 and 2025-03-26. A GET to the endpoint returns 405 with Allow: POST.

Scopes and connection presets

Authority is re-derived on every request and intersected with the authorising human's current grant, so demoting a member or revoking a key narrows what an existing credential can do without any cache to wait for. There are 32 scopes; sending uses messages:send, submitting a draft for review uses drafts:submit, and reading events uses events:read.

MCP consent offers three presets, and each maps to a fixed scope set:

Administrative scopes can never be attached to a connection: keys:manage, members:manage, billing:manage, policies:write, inboxes:delete, messages:delete, messages:raw and exports:write are refused on a grant. A connection holding only drafts:submit is treated as draft-only: its sends become approval requests even when the inbox permits direct sending. See sending controls and approvals for how that interacts with inbox policy.

Resource ID prefixes

Every identifier is a prefix plus a UUID, and the prefix is validated on input. Passing a thread ID where an inbox ID belongs fails immediately rather than resolving to something plausible.

Inbox IDs use ibx_. Most routes are nested under both the project and the inbox — for example POST /v1/projects/{project_id}/inboxes/{inbox_id}/messages — because a credential is scoped to projects and inboxes, and the path is what that scope is checked against.

Request and response rules

• Sends require an Idempotency-Key header. Without one the request is rejected with invalid_request before anything is created. See idempotency keys for agent email for the replay semantics.
• JSON bodies are capped at 1 MiB and read through a bounded reader, so an oversized body is refused with payload_too_large rather than buffered. Attachment content uploads are capped at 10 MiB instead.
• List endpoints return data, next_cursor and has_more. The default page is 25 items and limit accepts 1 to 100. A thread's message list defaults to 50. Cursors are covered in search and pagination.
• A successful send returns HTTP 202 with result: "queued", or result: "approval_required" when policy or a draft-only credential routes it to review. Neither means the message left the building yet.
• Every error shares one envelope and carries a request ID you can quote in a support thread.

{
  "error": {
    "code": "policy_denied",
    "message": "Workspace policy blocked this send.",
    "request_id": "req_...",
    "retryable": false,
    "details": { "reason_codes": ["blocked_recipient"] }
  }
}

retryable is computed, not decorative: it is true for rate_limited, provider_unavailable and temporarily_unavailable, and false everywhere else unless the specific call sets it. Retrying a non-retryable error changes nothing except your rate-limit budget.

Error codes and HTTP statuses

The whole set, with the status each one maps to. Branch on error.code, not on the status: several codes share a status and mean different things.

Limits enforced in code

These are checked on the request path, not published as guidance. Exceeding one returns an error rather than truncating your input.

The free allowance is one complimentary live inbox and 100 email units a month per verified owner identity, claimed by that identity's first eligible workspace. Creating a second workspace does not renew it. Pricing has the full wording.

Rate limits

Three counters run in production: 1,200 requests per 60 seconds per client IP at the edge, 600 per 60 seconds per principal, and 600 per 60 seconds per workspace. Exceeding any of them returns rate_limited with retry-after: 60.

Treat those numbers as a ceiling rather than a contract. The counters are Cloudflare rate-limit bindings, which are local to the edge location serving the request and deliberately permissive; the code that reads them says as much. They are protection against a runaway loop, not a metering system, and they are never billing authority.

Test mode and live mode

A project is created as test or live and cannot move between them; the attempt returns environment_immutable. The environment decides the transport.