Create mailboxes on demand, assign oversight modes, and track per-agent reputation — all through a single API. No manual provisioning, no shared inboxes.
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.
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), an independently configured oversight mode, and its own reputation tracking. You can provision hundreds of inboxes programmatically — one per agent, one per customer, one per workflow — and tear them down when you're done. 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.
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.
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.
Configure a webhook URL on the mailbox. MultiMail delivers a structured JSON payload to your endpoint for every inbound email: parsed headers, body, attachments, sender reputation signals, and a thread ID. Your agent reads the payload directly — no IMAP, no polling.
Use send_email or reply_email endpoints with the mailbox ID as the sender. 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.
MultiMail tracks delivery rate, bounce rate, and engagement signals independently per mailbox. Query the reputation endpoint to surface which agents are performing well and which are generating complaints — before they affect your domain's sender score.
curl -X POST https://api.multimail.dev/v1/mailboxes \
-H "Authorization: Bearer $MULTIMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d &"cm">#039;{
"name": "support-agent",
"domain": "yourcompany.multimail.dev",
"display_name": "Support Agent",
"oversight_mode": "monitored",
"webhook_url": "https://yourapp.com/webhooks/email"
}&"cm">#039;
"cm"># Response:
"cm"># {
"cm"># "mailbox_id": "mbx_01HZ9K2P3XQRV8TNWYD4G6F0E",
"cm"># "address": "[email protected]",
"cm"># "oversight_mode": "monitored",
"cm"># "created_at": "2026-04-19T10:00:00Z"
"cm"># }Provision a new mailbox with a custom local part, oversight mode, and display name. The response includes the full email address and the mailbox ID you'll use in subsequent API calls.
import multimail
client = multimail.Client(api_key="$MULTIMAIL_API_KEY")
"cm"># Check inbox for a specific mailbox
messages = client.check_inbox(
mailbox_id="mbx_01HZ9K2P3XQRV8TNWYD4G6F0E",
filter="unread",
limit=20
)
for message in messages.emails:
print(f"From: {message.sender}")
print(f"Subject: {message.subject}")
print(f"Thread: {message.thread_id}")
print(f"Preview: {message.body_text[:100]}")
print("---")
"cm"># Read full email if needed
if message.requires_action:
full = client.read_email(email_id=message.email_id)
print(full.body_text)Fetch unread messages from a specific mailbox. Returns structured email objects with parsed headers, body text, and thread IDs. The 'unread' filter is efficient for polling agents that need to process new arrivals.
import multimail
client = multimail.Client(api_key="$MULTIMAIL_API_KEY")
"cm"># Reply to an existing thread
result = client.reply_email(
thread_id="thr_01HZ9K2P3XQRV8TNWYD4G6F0E",
mailbox_id="mbx_01HZ9K2P3XQRV8TNWYD4G6F0E",
body_text="Thanks for reaching out. I&"cm">#039;ve reviewed your request and here's what I found...",
body_html="<p>Thanks for reaching out. I&"cm">#039;ve reviewed your request and here's what I found...</p>"
)
if result.status == "pending":
# Mailbox is in gated_send — message awaits human approval
print(f"Awaiting approval: {result.pending_id}")
elif result.status == "sent":
print(f"Sent: {result.message_id}")Send a reply using the thread ID to preserve the conversation chain. The mailbox's oversight mode determines whether the reply sends immediately (monitored/autonomous) or enters a pending state for human approval (gated_send).
curl https://api.multimail.dev/v1/mailboxes/mbx_01HZ9K2P3XQRV8TNWYD4G6F0E/reputation \
-H "Authorization: Bearer $MULTIMAIL_API_KEY"
"cm"># Response:
"cm"># {
"cm"># "mailbox_id": "mbx_01HZ9K2P3XQRV8TNWYD4G6F0E",
"cm"># "address": "[email protected]",
"cm"># "reputation_score": 94,
"cm"># "bounce_rate": 0.012,
"cm"># "complaint_rate": 0.001,
"cm"># "delivery_rate": 0.988,
"cm"># "messages_sent_30d": 847,
"cm"># "identity_verified": true
"cm"># }Fetch reputation metrics for a specific mailbox. Use this to monitor agent behavior over time and identify inboxes that are accumulating bounces or spam complaints before they affect domain health.
const response = await fetch(
'https://api.multimail.dev/v1/mailboxes/mbx_01HZ9K2P3XQRV8TNWYD4G6F0E',
{
method: 'PATCH',
headers: {
'Authorization': 'Bearer $MULTIMAIL_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
oversight_mode: 'monitored', "cm">// promote from gated_send
}),
}
);
const mailbox = await response.json();
console.log(`Updated: ${mailbox.address} → ${mailbox.oversight_mode}`);
"cm">// Updated: [email protected] → monitoredChange the oversight mode on an existing mailbox without recreating it. Useful for graduated trust workflows where you start an agent at 'gated_send' and promote to 'monitored' after it demonstrates reliable behavior.
Isolated mailboxes mean a misbehaving agent can't contaminate the delivery reputation or message history of other agents. When something goes wrong, you know exactly which mailbox — and which agent — caused it.
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.
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.
MultiMail tracks bounce rate, complaint rate, and delivery success independently per mailbox. This gives you the observability to catch reputation problems at the agent level before they propagate to your domain's shared sender score.
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.
Email infrastructure built for AI agents. Verifiable identity, graduated oversight, and a 50-tool MCP server. Formally verified in Lean 4.