Scouty runs on Mermail

Explore
Back to blog
Email7 min read

Create an Email Inbox per AI Agent by API: What to Check First

If agents are created by code, their inboxes should be too. Here is what an inbox API must do for agents, and how to create one mailbox per agent safely.

By Toan Nhu

Mermail field guide cover reading One inbox per agent, by API., with one POST request creating three agent mailboxes

Your agent signs up for a tool at 2 p.m., needs a verification code at 2:01, and is stuck at 2:02 because nobody made it an address. Someone opens an admin panel, creates a mailbox by hand, pastes the password into a config file, and the agent finally moves on.

That works for one agent. It falls apart at ten. If agents are created by code, their inboxes should be too.

What "create an inbox by API" really has to mean

Plenty of services can return a new email address from a single HTTP call. That is the easy part. For an agent, the address is only useful if the answer to all of these is yes:

  1. It is live when the call returns. No DNS wait, no license assignment, no admin approval queue.
  2. It receives mail from the outside world, not only from a test harness.
  3. It can send and reply from the same address, so a conversation stays in one thread.
  4. Your code can read it through an API, a webhook or an MCP tool, without a person logging in.
  5. It can be retired cleanly when the agent is done.

Check every candidate against that list before you compare prices.

Three kinds of service, three different jobs

Services that hand out inboxes over an API tend to fall into three groups. Each is good at something; only one was designed around agents.

Agent-native inbox APIs

Built for software that owns its own mail. You create a mailbox, it accepts external mail right away, and you read and send through an API. This is the group to evaluate for production agents.

Test inbox tools

Built for QA. They give you disposable addresses so a test suite can catch a signup email and assert on it. They are great inside CI. They are usually a poor home for an agent that needs to reply to real people, keep history, or send from a domain with a reputation you care about.

Workspace admin APIs

Built for HR and IT. The call creates a user account for a person, often with a paid seat, a password policy and a login. You can automate it, but you are provisioning an employee, not an inbox. Reading that mailbox from code then needs a second set of credentials and consent.

A quick way to tell them apart: ask what the provider bills you for. Seats point to a workspace tool. Test runs point to a QA tool. Mailboxes and messages point to an agent inbox.

Why the usual shortcuts break

  • One shared inbox for every agent. Verification codes from ten services land in one place, and the agent has to guess which code belongs to which signup. We covered the trade-offs in Catch-All Domain or One Mailbox per Agent?.
  • Plus addressing on a personal account. Handy for filtering, but the agent can now read everything else in that account.
  • Manual creation in a dashboard. Fine for a demo. In production it becomes a ticket every time an agent spins up, and a forgotten mailbox every time one is retired.

How Mermail creates a mailbox per agent

Mermail gives each agent its own mailbox and exposes it through a REST API, an MCP server and a CLI. Creating one is a single authenticated call.

The sold API, with an API key

Create a key in the console under Settings, API Keys. Each key is bound to one workspace, so an agent can only provision mailboxes where you allowed it.

bash
curl -X POST https://console.mermail.app/api/v1/mailboxes \
  -H "x-api-key: $MERMAIL_API_KEY" \
  -H "Idempotency-Key: signup-agent-acme-v1" \
  -H "Content-Type: application/json" \
  -d '{"email": "signup-agent@mermail.app", "name": "Signup agent"}'

A few details that matter in practice:

  • It returns `201` and the mailbox can receive mail as soon as it exists.
  • `email` and `name` are required, and the call needs workspace admin rights.
  • Pass an `Idempotency-Key`. If the network drops and you retry with the same key and body, you do not get a second mailbox. After a conflict or an unclear answer, list your mailboxes and look for the address before trying again.
  • It costs 10 provision credits from your workspace API credit balance. Credits are usage units, not dollars.

The keyless marketplace API, paid by wallet

Some agents should not hold an API key at all. Mermail also runs a keyless inbox API at https://console.mermail.app/api/agent/v1 where payment is the credential. The agent pays in USDC over x402 (or MPP), and the paying wallet owns the inboxes it creates.

  • The listed price to create a hosted inbox is $2.00; reads, searches and saving drafts are $0, and an unpaid call returns 402 with the live quote.
  • One wallet can hold up to 50 hosted inboxes.
  • New inboxes start in verification mode with automations off, and message bodies are only returned after a clean scan.
  • Custom domains, webhooks and workspace admin are not part of this surface. Use the sold API or MCP for those.

From an AI assistant, over MCP

If your agent lives in Claude, Cursor, Codex or another MCP client, connect Mermail MCP with OAuth and ask it to find or create a mailbox. The restricted agent-inbox profile limits the agent to a small set of mailbox tools, which is what you want for a signup bot. The agent email inbox guide walks through the discover-or-create flow.

Pick the right shape for your fleet

There is no single right answer. Use the number of agents, the domain and how long each inbox lives to decide.

  • One agent, testing an idea. A hosted @mermail.app address on the Free plan, which includes one inbox.
  • A handful of production agents. The Developer plan includes five inboxes and one custom domain. Put agents on a dedicated subdomain such as mail.example.com so your company mail is untouched. See Give Your AI Agent an Address on Your Own Domain.
  • Many short-lived identities for one agent. Before creating another mailbox, check whether a plus alias does the job. When aliases are available on a hosted mailbox, agent+receipts@mermail.app works immediately and shares that mailbox's limits and storage.
  • Agents that pay for themselves. The keyless marketplace API, so the wallet that pays is also the owner.
  • Thousands of inboxes or a private deployment. Talk to Mermail about Enterprise limits, and read Custom Domains for Thousands of Agent Inboxes.

A provisioning checklist you can paste into a ticket

  • The create call is idempotent, and your code lists mailboxes before retrying.
  • The address name says which agent and which job it belongs to.
  • Each third-party signup gets its own mailbox or alias, never a shared one. See One Service, One Mailbox.
  • Inbound content is treated as untrusted, and verification codes are matched to the exact sender and time window.
  • You have a written plan for retiring the inbox. See How to retire an AI agent without losing its email accounts.

Ready to try it? Create your first agent mailbox in the Mermail console, then script the same call.

FAQ

Can I create an email inbox for an AI agent with one API call?

Yes. With Mermail, a POST /api/v1/mailboxes request with an API key creates a hosted or custom-domain mailbox and returns 201. A keyless version paid by wallet is also available.

How fast is the new inbox ready?

A Mermail mailbox can receive mail as soon as the create call succeeds. Custom domains need their DNS records verified once, before mailboxes move to that domain.

Should test inboxes and production agent inboxes come from the same place?

Keep them apart. Test inboxes are meant to be thrown away, while a production agent needs history, replies and a sending reputation you protect.

Do inboxes on the same domain share reputation?

Yes, mail from one domain builds a shared reputation, which is why a dedicated subdomain for agents is a good idea. SPF, DKIM and DMARC for AI Agent Email covers the setup.

What happens if my create request times out?

Retry with the same Idempotency-Key and body, or list your mailboxes first and check whether the address exists. Do not retry blindly with a new key.

References

Recent articles