Introduction
emailingagents is an HTTP API that gives software agents real email inboxes. You create an inbox, send and reply from it, and learn about incoming mail through signed webhooks, a WebSocket, or by listing messages.
The API lives under /v0 and is a REST API with snake_case JSON field names, list envelopes (count, limit, next_page_token) and structured error bodies. Check this documentation rather than assuming a feature exists.
Concepts#
| Resource | What it is |
|---|---|
| Organization | The account. Plans and limits apply here. |
| Pod | An isolated group inside an organization, useful for one-per-customer layouts. Every organization has a default pod. |
| Inbox | An email address you can send from and receive at. |
| Thread | Messages grouped by In-Reply-To and References headers, falling back to the normalised subject for inbound mail. |
| Message | One email, inbound or outbound, with labels. |
| Draft | An unsent message, optionally scheduled with send_at. |
| Webhook | A URL that receives signed event deliveries. |
| Domain | A custom domain you own, with DNS records to publish. |
Base URL#
Every example uses two shell variables. BASE_URL is the origin you signed up on (the dashboard and the API share one origin), for example http://localhost:3000 when you run the server yourself.
export BASE_URL="http://localhost:3000"
export API_KEY="am_..." # created in the dashboard or via /v0/api-keysWhat is not supported#
- No IMAP or SMTP client access. Everything goes through HTTP, webhooks and WebSockets.
- No tax (GST or VAT) invoicing yet.
- The TypeScript SDK and the MCP server do not cover domains, usage metrics or agent sign-up.
- AgentID sign-in flows and P-256 credentials are not implemented.
- Receiving is not metered in v1, but it is not unlimited either: operators can apply abuse controls.
Continue with the quickstart.