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. It is in early access: read status and early access and check the feature table rather than assuming a feature exists.

How it works#

Solid arrows are outbound and point away from your agent; dashed arrows are inbound and point back toward it. Inbound ends in a webhook, a WebSocket event or a list call.

Your agent calls the API. One HTTPS request with an API key creates an inbox, sends, replies or reads. The TypeScript SDK, the Python SDK and MCP tools make the same calls.
The API hands the message to an email provider. It checks permissions, plan limits, block lists and suppressions first, stores the message and threads it.
The provider delivers it to the recipients. Delivered, bounced and complained events come back and become labels, events and suppressions.
Replies come back the same way. The provider passes inbound mail to the API, which parses it, joins the right thread, strips the quoted chain into extracted_text and tells your agent through a signed webhook or a WebSocket event. You can also just list messages.

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.
API key	A secret that lets code call the API, optionally limited to a pod or inbox and to named permissions.

The glossary defines every term used in these docs.

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-keys

Ways in#

Getting started has a short path for each of the dashboard, REST, the TypeScript SDK, the Python SDK and MCP.

What is not available#

IMAP and SMTP client access and AgentID sign-in are not built and not planned. Everything goes through HTTP, webhooks, WebSockets and MCP.
Sending from and receiving on your own domain is not connected yet; DNS record generation and verification work. See domains.
Some features work through the API but have no dashboard screen yet: forward, scheduled send, search, attachments. The feature table is generated from the code and always current.
The SDKs and the local MCP server are not published to npm or PyPI yet.
No tax (GST or VAT) invoicing yet.
Receiving is not metered in v1, but it is not unlimited either: abuse controls and message size limits apply.

Continue with getting started or the quickstart.