Mailbox for AI Agents: Provision One via API

A mailbox for AI agents is a real, addressable inbox your code creates on demand: one POST request returns an address that can send mail, receive mail, and hold threads. No SMTP host to configure, no OAuth consent screen, no human clicking through a provider setup wizard. The agent gets an identity on the public email network in the same amount of code it takes to create a database row.

That is the whole difference between an agentic mailbox and the usual approach. Traditional email access assumes a person exists behind the address. Agent mailboxes assume a program does.

What an agentic mailbox actually needs

Agents use email differently than humans do. A person opens a client, reads, decides, replies. An agent needs the mail delivered to it as data, on an event, with enough context to continue a conversation it started an hour or a week ago.

In practice that means four things:

1. A real address on a real domain. Vendors, suppliers, candidates, and customers reply to it. It must accept inbound mail from anywhere, not just from your own systems.
2. Programmatic send. JSON in, message out, with a message id you can store.
3. Push delivery of inbound mail. A webhook that fires when mail arrives, so you are not polling IMAP on a cron.
4. Threading that survives. Every inbound message carries a thread id, so the agent can load prior turns and reply in the same conversation rather than starting a new one.

Anything missing from that list turns into glue code you maintain forever. Missing threading in particular is why so many agent email projects produce conversations that read like amnesia.

One API call

Creating the mailbox is the part that should be boring. Here it is with the CLI:

npx @robotomail/cli mailbox create shopping-agent

Or over HTTP:

curl -X POST https://api.robotomail.com/v1/mailboxes \
  -H "Authorization: Bearer rm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"address": "shopping-agent"}'

That returns a mailbox with an address like shopping-agent@robotomail.co. It is live immediately: it can send, and mail sent to it from any provider on the internet will arrive. Add domainId with your own domain's UUID if you want the address on a domain you control.

Sending is one more call:

curl -X POST https://api.robotomail.com/v1/mailboxes/mbx_shopping/messages \
  -H "Authorization: Bearer rm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"to": ["vendor@example.com"], "subject": "Order #A-4521 delivery update?", "bodyText": "Hi, checking on the status of order A-4521."}'

Register a webhook, and inbound mail arrives as JSON:

{
  "event": "message.received",
  "data": {
    "message_id": "...", "mailbox_id": "...", "mailbox_address": "shopping-agent@robotomail.co",
    "from": "vendor@example.com", "subject": "Re: Order #A-4521 delivery update?", "body_text": "...",
    "thread_id": "...", "received_at": "2026-04-17T10:00:00.000Z"
  }
}

To reply in the same conversation, send with inReplyTo set to the inbound message_id. That is the full loop. The quickstart walks it end to end in a few minutes.

Contrast: the SMTP path

If you skip the API route, the shortest honest version of the SMTP approach looks like this:

1. Pick a domain and decide whether the agent lives on the root domain or a subdomain.
2. Publish MX records so inbound mail routes somewhere you control.
3. Publish SPF, DKIM, and DMARC so your outbound mail is not filed as spam.
4. Configure an SMTP relay: host, port, username, password, TLS mode, and whatever quirk that provider has about From header rewriting.
5. Stand up an inbound path. This is the part people underestimate. SMTP is a sending protocol. Receiving means either running an MTA that accepts connections on port 25, or configuring a provider's inbound parse feature, or polling IMAP.
6. Store credentials somewhere the agent can reach them without leaking them into a prompt or a log.
7. Handle MIME parsing yourself: multipart bodies, quoted-printable, base64 attachments, character sets, and the reply quoting that every client formats differently.
8. Reconstruct threading from Message-ID, In-Reply-To, and References headers, and accept that some clients mangle them.

None of these steps are unreasonable. We run mail infrastructure, so we do them all. They are just not the problem you set out to solve when you decided your agent should be able to email a supplier. And step 5 plus step 7 is where projects stall, because IMAP polling loops and MIME parsers are where the ugly edge cases live.

There is also a scaling wrinkle. SMTP credentials are per-account, not per-agent. If you want ten agents with ten distinct addresses, you are either creating ten mail accounts by hand or fanning out from one address and doing your own routing on the To header. Neither ages well past a handful of agents.

Contrast: the OAuth path

The other common instinct is to hand the agent a Gmail or Outlook account, which means OAuth. The mechanics are worse than they look for autonomous software:

• Consent is human-shaped. The flow assumes a browser, a person, and a click. Automating it means either headless-browser hacks or a one-time manual setup per agent, which defeats the point of provisioning agents programmatically.
• Refresh tokens expire and get revoked. Password changes, security reviews, and inactivity policies all invalidate them. Your agent stops working at 3am and the fix is a human logging in.
• Scopes are coarse. Full mailbox read plus send is a large blast radius for a program with a model in the loop. Restricted scopes often require a verification review.
• Sending appears as a person. Mail from a shared human account attributed to an agent is a compliance and audit headache. Who sent that? The person named in the From header did not.
• Rate and quota behavior is designed for human volume, and the throttling messages are not always precise about which limit you hit.

We wrote up the tradeoffs in more detail in the Gmail API comparison, including where the Gmail route still makes sense: when the agent's job is genuinely to work inside a specific person's existing inbox.

Comparison at a glance

	Agentic mailbox API	SMTP relay + inbound parse	Gmail/Outlook OAuth
Time to first address	One API call	DNS plus relay config	Consent flow per account
Receive inbound	Webhook, JSON body	MTA, parse hook, or IMAP poll	API pull or push notifications
Per-agent identity	Create as many as you need	One account per address	One account per address
Credential model	API key, server side	SMTP user and password	Refresh tokens that expire
Threading	Thread id on every message	Parse headers yourself	Provider thread id
MIME parsing	Done for you	Yours to write	Base64 payload decoding

Provisioning patterns that hold up

One mailbox per agent. The default. support-agent@, recruiter@, invoices@. Clear identity, clear audit trail, easy to revoke one without touching the others.

One mailbox per task or run. Useful for anything short-lived: a single procurement negotiation, one candidate pipeline, a research sweep where you want the replies isolated. Create it at the start of the run, tear it down when the run closes. This is only practical when creation is an API call.

One mailbox per customer in a multi-tenant product. If you ship an agent to your users, each tenant gets an address on your domain. Provision it during onboarding, in the same transaction that creates the tenant.

Whichever pattern you use, keep the routing logic in your dispatcher, not in the model. The webhook tells you mailbox_id and thread_id. Use those to look up which agent owns the conversation and load its state, then hand the model only the message body and the prior turns it needs. Details on payload handling and retry behavior live in the webhooks concepts page.

Threading is the part that makes it feel real

An agent that replies without context produces the same email over and over. The fix is not prompt engineering, it is state.

Every message we deliver carries a thread_id. Store it alongside your agent's conversation state and you get a durable key: inbound message arrives, look up the thread, load the turns, generate the reply, send with inReplyTo set to the inbound message id. The recipient's client stacks it in the same conversation, which matters because a human on the other end judges your agent partly on whether its replies land in the right place. See threading for how thread ids are assigned across forwards and subject changes.

What still requires care

Provisioning being easy does not make deliverability automatic.

• Warm up custom domains. A brand new domain sending negotiation emails at volume on day one will see filtering. Start slow.
• Publish SPF, DKIM, and DMARC if you use your own domain. Platform-domain mailboxes are already authenticated.
• Reply, do not blast. Agent mailboxes earn reputation from conversations. Cold volume from an agent address burns it fast.
• Keep a human review path for anything with money or legal consequence. Give the agent a mailbox, not unlimited authority.
• Log every send and receive with mailbox id, thread id, and message id. When someone asks what your agent told a customer in March, you want an answer.

FAQ

What is the difference between an agentic mailbox and a normal email API?

Most email APIs are send-only: they push transactional or bulk mail out and stop there. An agentic mailbox is bidirectional and stateful. It has a real address that accepts inbound mail from anywhere, delivers it to your code by webhook, and keeps thread identity so replies chain correctly.

Can I give each agent in a multi-agent system its own address?

Yes, and you generally should. Create one mailbox per agent with a distinct address so routing, permissions, and audit logs are unambiguous. Because creation is a single API call, this scales to hundreds of agents without manual setup.

Do I need my own domain?

No. Mailboxes created without a domainId live on a platform domain and are ready to send and receive immediately. Add a custom domain when you want the address to carry your brand, which means publishing DNS records and warming the domain up.

Can the agent handle attachments?

Yes. Inbound attachments are parsed out for you rather than left as raw MIME, and you can attach files on send. If your agent processes invoices or contracts, this is usually the first thing it needs after basic send and receive.

Ready to give your agent an address? Create your first mailbox in a single call at robotomail.com.