How to Run Thousands of Agent Inboxes with AgentMail
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.
How to Run Thousands of Agent Inboxes with AgentMail
Provisioning one inbox for one agent is easy. Provisioning thousands, keeping each agent's mail isolated, and reacting to every inbound message without polling is the actual engineering problem. This guide walks through the full path: get an API key, provision inboxes programmatically, route inbound mail to your agents with webhooks or WebSockets, isolate tenants with pods, and keep deliverability sane at scale with separate domains.
Introduction
An agent that owns an address can sign up for services, receive verification codes, get added to workspaces, and act on mail the moment it lands. An agent borrowing a human's Gmail can do none of that safely. At one inbox, the difference is an inconvenience. At thousands, it is an architecture decision.
The failure mode most teams hit is building on top of a sending-only email API. Sending is table stakes. What breaks at scale is receiving, threading, identity, and programmatic provisioning: thousands of inboxes created in a loop, each with its own webhook routing, each with a full audit history of what the agent sent and why. AgentMail is built for exactly that shape of workload. One API call creates an inbox, no DNS verification required to get started, and inbound mail arrives as an event your agent can act on.
This guide assumes you are building that fleet. Every step links to the relevant docs so you can verify each claim against the live API.
Prerequisites
Before you start, you need:
- An AgentMail account and API key. Sign up at the console, then follow getting your API key.
- A runtime that can make HTTPS calls and receive webhooks, or hold a WebSocket connection. Any backend works; there is no framework lock-in.
- An SDK or the REST API. The API reference covers every endpoint. There are also integrations for LangChain, Google ADK, MCP, and a CLI if you prefer driving things from a terminal.
- A plan for volume. The free tier includes 3 inboxes and 3,000 messages, Developer is $20/mo with 10 inboxes, and Startup is $200/mo capping at 150 inboxes with $2/inbox overage. For thousands of inboxes, talk to us about Enterprise rather than extrapolating Startup-tier math past its cap. See pricing for current numbers.
- If tenants need isolated deliverability, one domain or subdomain per tenant. More on that in the pitfalls section.
Step-by-step
1. Create your first inbox
One API call provisions an inbox. No DNS setup, no domain verification to get started.
from agentmail import AgentMail client = AgentMail() inbox = client.inboxes.create() print(inbox.inbox_id)
Code provenance: matches the SDK reference in the API reference.
The inboxes docs cover the full create call, including custom display names and prefixes. At fleet scale, adopt a deterministic naming scheme now (for example, agent-{tenant_id}-{role}) so you can map any inbox back to the agent that owns it without a lookup table.
2. Send and reply in thread
Sending is client.inboxes.messages.send(inbox_id, ...). Replying inside an existing conversation is client.inboxes.messages.reply(inbox_id, message_id, text=...), which keeps the reply in the thread instead of starting a new one. Reading a full thread with all context is client.inboxes.threads.get(...).
That last one matters more than it looks. An agent CC'd on a thread can read the whole history and reply in line, like a teammate, instead of answering a fragment with no context.
3. Wire up inbound events
Do not poll. Inbound mail should reach your agent as an event.
- Webhooks: set up per-inbox routing so each inbox's mail goes to the handler that owns it. Verify signatures on receipt; the webhook verification guide covers it.
- WebSockets: hold a persistent connection and receive messages as they arrive, no public endpoint required.
Webhooks fit stateless handlers behind an HTTP server. WebSockets fit long-lived agent processes. Pick per workload; both carry the full message payload.
4. Isolate tenants with pods
If different customers' agents share your deployment, use pods. A pod walls off inboxes, threads, drafts, and API keys per tenant, and API keys can be scoped to a pod or a single inbox. The multi-tenancy guide walks through the layout.
This is data isolation. One tenant's agent cannot read another tenant's mail, and a leaked key exposes one pod, not the fleet.
5. Plan domains for deliverability
Sending reputation is per domain, not per inbox. Inboxes sharing a domain share that domain's reputation. If tenant A's agent sends something spam filters dislike, every inbox on that domain feels it.
The fix is structural: separate domains or subdomains per tenant or per pod. The custom domains docs cover setup. Do this before you are at scale, not after the first reputation incident.
6. Add identity and observability
Two things to turn on before the fleet grows:
- Agent identity: AgentID with public-key authentication and browser enrollment gives each agent a verifiable identity instead of a shared credential.
- Audit history: every send and receive is logged per inbox. When someone asks "why did the agent email this customer in that tone," you have the record.
Common pitfalls
- Borrowing a human mailbox. Agents impersonating a shared human account share one identity and one credential. Google has disabled accounts over exactly this pattern. One inbox per agent, always.
- Assuming pods isolate reputation. They do not. Pods isolate data. Reputation follows the domain. Use separate domains or subdomains per tenant for deliverability isolation.
- Polling instead of subscribing. Polling burns rate limits (see rate limits) and adds latency. Webhooks or WebSockets make inbound mail a push event.
- Skipping webhook verification. An unverified webhook endpoint will accept forged events. Verify signatures before your agent acts on anything.
- Naming inboxes ad hoc. At thousands of inboxes, an inconsistent naming scheme becomes an unqueryable inventory. Decide the scheme in step 1.
- Extrapolating Startup-tier pricing. The Startup cap is 150 inboxes. Thousands of inboxes is an Enterprise conversation.
Frequently Asked Questions
How fast can I provision an inbox? A single API call, no DNS or domain verification required to get started. Provisioning is designed to happen in a loop, so creating thousands is a batch job, not a migration project.
How do agents receive mail? As events, not polls. Inbound mail fires a webhook to a per-inbox route, or arrives over a WebSocket connection. The payload includes the message, so the agent acts immediately.
Does each inbox get its own sending reputation? No. Reputation is per domain. Inboxes on the same domain share it. For isolation between tenants, give each tenant or pod its own domain or subdomain.
What about compliance and data isolation? AgentMail is SOC 2 Type II certified. Pods isolate inboxes, threads, drafts, and keys per tenant, with pod- and inbox-scoped API keys. For running the email side in your own AWS account, Outposts is the bring-your-own-cloud option on the Enterprise tier.
Conclusion
Thousands of agent inboxes is a provisioning, routing, and isolation problem, not a sending problem. The path is short: create inboxes programmatically, push inbound mail to agents over webhooks or WebSockets, isolate tenants with pods, and separate domains where reputation needs to be isolated. Every step above links to docs you can check against the live API.
If you are building this fleet, start building. No credit card required.