Programmatic Inbox Management for AI Agents

Create mailboxes on demand, assign oversight modes, and sign every outbound message per mailbox — all through a single API. No manual provisioning, no shared inboxes.


Why this matters

Most email infrastructure assumes a human will log in and manage an inbox. When you're building multi-agent systems, that assumption breaks down immediately. Agents need their own isolated addresses, and those addresses need to be provisioned, configured, and decommissioned at runtime — not through a web UI. Shared inboxes create attribution problems: you can't tell which agent sent what, and a misbehaving agent contaminates the reputation of every other agent on the same address. You also need per-inbox oversight controls. The agent handling customer support shouldn't operate under the same autonomy level as the one sending internal reports.


How MultiMail solves this

MultiMail's Inbox API lets you create a mailbox with a single POST request. Each mailbox gets a dedicated address (either on your custom domain or at multimail.dev) and an independently configured oversight mode. You can provision mailboxes programmatically — one per agent, one per customer, one per workflow — and tear them down when you're done, within your plan's mailbox limit. Inbound email triggers webhooks to your endpoint. Identity signing is applied per-mailbox, so recipients can verify that mail came from the specific agent you authorized. Sender reputation is tracked at the account level and published as a verifiable hash on every outbound message.

1

Create a mailbox via API

POST to /v1/mailboxes with a name, optional custom domain, and an oversight mode. The response includes the assigned email address and mailbox ID. Creation is synchronous — the address is live immediately.

2

Configure oversight mode

Set the oversight mode at creation time or update it later. For inbox management at scale, 'monitored' is the recommended default: agents operate autonomously while a human receives notifications of all activity. Sensitive workflows can be set to 'gated_send' to require approval before any email leaves the mailbox.

3

Receive inbound email via webhook

Register a webhook (POST /v1/webhooks) subscribed to message.received. MultiMail POSTs a structured JSON payload to your endpoint for every inbound email — including the email_id, from, to, subject, direction, and has_attachments. Read the full message by id to get the body and attachment metadata. Your agent reacts directly — no IMAP, no polling.

4

Send and reply

POST to /v1/mailboxes/{mailbox_id}/send to send, or /v1/mailboxes/{mailbox_id}/reply/{email_id} to reply in thread. Each outbound message is identity-signed. If the mailbox is in 'gated_send' mode, the message enters a pending state and your human operator receives an approval request before delivery.

5

Reputation travels with the mail

Every outbound message carries an X-MultiMail-Reputation header — a hash that resolves to the account's published sender standing at GET /.well-known/reputation/{hash}. Reputation is tracked at the account level; to review a specific mailbox's recent activity, list its messages and inspect delivery and bounce statuses.


Try it with your agent

Pick your platform, copy the prompt, and paste it to your AI agent — it sets up MultiMail and builds the whole flow. Nothing to fill in.

1. Get MultiMail ready: read https://multimail.dev/llms.txt, connect the MCP server, create a free inbox, and set up a verified sender. 2. In n8n, build a workflow that starts with the Webhook Trigger node for agent-provisioning requests, then use n8n’s HTTP Request node only for the business app that tells you which agent, customer, or workflow needs email. 3. For each request, create a dedicated MultiMail inbox named for that agent or workflow, record the assigned address in the workflow data, and use it for all compose, send, and scheduled email actions tied to that agent. 4. Add a second n8n workflow that starts from MultiMail inbound email events and routes each message back to the matching agent by inbox address, preserving attribution in the workflow run history. 5. Run every new inbox in monitored mode by default; ask me only for n8n credentials, the sender domain, and brand voice before turning the workflows live.

What you get

One inbox per agent, not one inbox for all agents

Isolated mailboxes mean each agent has its own address, identity signature, and message history — a misbehaving agent can't pollute another agent's inbox or impersonate it. When something goes wrong, you know exactly which mailbox — and which agent — caused it.

Runtime provisioning without manual steps

Creating a mailbox is a single API call that returns a live address within milliseconds. No DNS configuration, no admin panel, no support ticket. You can provision mailboxes dynamically as agents spin up and decommission them when workflows complete.

Per-mailbox oversight modes

Assign different autonomy levels to different inboxes based on risk. A customer-facing support agent can run in 'gated_send' while an internal analytics agent runs 'monitored'. Oversight mode changes take effect immediately and don't require reprovisioning.

Published, verifiable sender reputation

MultiMail tracks delivery outcomes and complaints at the account level and publishes the standing as a hash on every outbound message (X-MultiMail-Reputation). Any recipient can resolve that hash at the public well-known endpoint — reputation is verifiable by the people you send to, not just visible to you.

Identity signing on every outbound message

Each mailbox signs outbound mail with a per-mailbox identity key. Recipients and downstream systems can verify that a message came from the specific agent authorized to use that address — not just from your domain in general.


Recommended oversight mode

Recommended
monitored
Inbox management at scale requires agents to operate without human approval on every action — the volume makes gated flows impractical. 'Monitored' mode lets agents create mailboxes, read inbound mail, and send replies autonomously while giving operators full visibility into all activity. If an agent starts generating complaints or bounces, you see it in the notification stream before it becomes a deliverability crisis. Reserve 'gated_send' for mailboxes that handle external customer communication until you've established a baseline for that agent's behavior.

Common questions

Can I use my own domain for mailboxes, or only multimail.dev addresses?
Both. You can provision mailboxes on any domain you've verified in your MultiMail account by adding an MX record pointing to MultiMail's inbound servers. If you don't have a domain to configure, multimail.dev subdomains are available immediately with no DNS setup required.
How many mailboxes can I create?
Builder plan supports up to 5 mailboxes, Pro supports 25, and Scale supports 100. Mailboxes can be decommissioned and reprovisioned within these limits — you're not locked to specific addresses permanently.
What does the inbound webhook payload look like?
The message.received webhook delivers a JSON object wrapped as { event, timestamp, data }, where data carries email_id, from, to, subject, direction, and has_attachments. To get the full parsed email — body and attachment metadata — read the message by its email_id (GET /v1/mailboxes/{mailbox_id}/emails/{email_id}). Attachment content is stored in MultiMail's encrypted object storage and fetched on demand by filename, optionally via a one-hour signed URL.
Can I query inbox history without a webhook?
Yes. The check_inbox endpoint supports filtering by read/unread status, date range, sender, and subject. For high-volume mailboxes, webhooks are strongly preferred — polling at scale creates unnecessary latency and rate limit pressure. Use check_inbox for low-volume or interactive workflows where push delivery isn't practical.
What happens to pending messages if I change the oversight mode from gated_send to monitored?
Existing pending messages remain in their pending state and still require explicit approval or cancellation. The oversight mode change only affects new outbound messages created after the update. You can use the list_pending endpoint to view and resolve outstanding approvals after a mode change.
How does sender reputation tracking work?
MultiMail tracks delivery outcomes and complaint signals at the account level and publishes the resulting standing as a hash on every outbound message via the X-MultiMail-Reputation header. Anyone who receives your mail can resolve that hash at the public endpoint GET /.well-known/reputation/{hash} to read the published standing (rate-limited, cached ~1 hour). There is no authenticated per-mailbox reputation route — to review a specific mailbox's recent activity, list its messages and inspect their delivery and bounce statuses.
Can I use the Inbox API from MCP clients like Claude Desktop?
Yes. The create_mailbox MCP tool is available in the MultiMail MCP server, which exposes 51 tools covering mailbox provisioning, inbox management, sending, and oversight. Connect Claude Desktop, Cursor, or any MCP-compatible client to mcp.multimail.dev and use the create_mailbox tool directly from your agent's context.

Explore more use cases

The only agent email with a verifiable sender

Email infrastructure built for AI agents. Verifiable identity, graduated oversight, and a hosted MCP server. Formally verified in Lean 4.