How to Scale Agent Email Infrastructure 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 Scale Agent Email Infrastructure with AgentMail
The first agent inbox is a demo. The tenth is an architecture problem. This guide walks through the path from a handful of agents to a fleet: provisioning inboxes per agent, wiring inbound events so nothing polls, isolating tenants with pods, separating sending reputation with domains, and putting observability in place before something goes wrong. Every step maps to a documented AgentMail capability, and the whole thing is buildable in an afternoon, not a quarter.
Introduction
Most teams start the same way. One agent, one inbox, maybe a shared Gmail account with an app password, and it works. Then the fleet grows: a support agent, a sales agent, a recruiting agent, a scheduling agent. The shared inbox becomes a shared identity. Replies from different conversations collide in one thread. Nobody can say which agent sent what, or why. And when Google disables the account because an automation logged in from twelve places at once, you learn what shared credentials cost.
The fix is not more scripts around the mailbox. It is treating email as infrastructure: an inbox per agent, provisioned by API, with inbound events pushed to your code and every send and receive logged. That is what AgentMail is built for. It is the identity and email layer for AI agents: give any agent its own inbox, its own domain, and a full audit history of everything it sends and receives. This guide shows how to set that up so it holds at scale.
Prerequisites
Before you start, have the following in place:
- An AgentMail account and API key. Sign up at the console. The free tier includes 3 inboxes and 3,000 messages, which is enough to build and test the whole setup. The getting your API key guide covers key creation.
- An agent framework or plain code. AgentMail drops into LangChain, Google ADK, the OpenAI Agents SDK, the Vercel AI SDK, an MCP server, or your own loop. Nothing here depends on a specific framework.
- A place to receive webhooks. Inbound mail arrives as webhook events, so you need an HTTPS endpoint your agents can reach. WebSockets are an alternative if you would rather hold a connection open.
- A domain plan. If agents will send to real customers, decide early which domain or subdomain each tenant uses. This matters for deliverability, and it is cheaper to decide now than to migrate later.
- Rough tenant boundaries. Know which agents belong to which customer or workspace before you create inboxes. Retrofitting isolation is the painful version.
Step-by-step
1. Provision one inbox per agent, programmatically
An inbox is a single API call. No DNS verification, no waiting on propagation. Create one per agent, named after the agent's role, so support@, recruiting@, and scheduling@ are separate addresses with separate histories. The inboxes docs and the quickstart cover creation. If your fleet grows dynamically, create inboxes at agent-creation time and delete them when the agent is torn down. Email becomes a primitive you call like any other API.
2. Wire inbound events instead of polling
Set up a webhook endpoint and register it per inbox. When a reply lands, your agent gets the event, including the message body, and acts immediately. No cron job scraping a mailbox, no race between two agents reading the same message. The webhooks overview covers setup and webhook verification covers signing, which you should enable before production. If your agent is long-lived, WebSockets give you the same push model over a persistent connection.
3. Work in threads, not individual messages
An agent CC'd on a thread should read the whole history and reply in line, like a teammate. Use the threads API to pull context and reply within the thread rather than firing standalone messages. This is what keeps a recruiting agent's conversation with a candidate from colliding with its conversation with a hiring manager. Threads, drafts, labels, and attachments are all first-class, so the agent's mailbox behaves like a mailbox, not a send log.
4. Isolate tenants with pods and scoped keys
When multiple customers share the deployment, put each tenant's inboxes in a pod. Pods isolate data: inboxes, threads, drafts, and API keys stay walled off per tenant, and webhook routing is per inbox, so inbound events reach only the owning tenant's handler. Use pod- and inbox-scoped API keys so a compromised key for one tenant cannot read another's mail. The multi-tenancy guide walks through the full setup.
5. Separate sending reputation with domains
One correction that saves people months: sending reputation is per domain, not per inbox. Inboxes sharing a domain share that domain's reputation, and pods do not change that. If tenant A's agent sends something spammy, every agent on that domain feels it. The fix is separate domains or subdomains per tenant or per workload, managed through custom domains. Decide the mapping early, because it is the one piece of this architecture that is genuinely annoying to change later.
6. Turn on observability before you need it
Every send and receive is logged per inbox, which gives you a full audit history per agent. Make it part of your operating loop: when someone asks why an agent emailed a customer, the answer is a query, not an archaeology project. Rate limits are documented in the knowledge base, so read them before you design a burst-send workflow, not after one gets throttled.
Common pitfalls
- Sharing one inbox across agents. It looks cheaper until two agents reply to the same thread and you cannot tell which one did. One inbox per agent, always.
- Borrowing a human's mailbox. Shared credentials mean a shared identity, and providers have disabled accounts over exactly this. Give the agent its own address.
- Assuming pods isolate deliverability. They isolate data, not reputation. Reputation follows the domain, so plan domains per tenant.
- Polling instead of subscribing. Polling adds latency and double-processing bugs. Webhooks or WebSockets push the event to you.
- Skipping webhook verification. An unverified endpoint will accept forged events. Enable verification before production traffic.
- Leaving the free tier's inbox count as the plan. The free tier is 3 inboxes; the Developer tier is 10 for $20/month and the Startup tier caps at 150 with $2/inbox overage. Past that, pricing is Enterprise. Check the pricing page against your fleet size before committing.
Frequently Asked Questions
Do I need to verify a domain before I can create an inbox? No. Inboxes are provisioned in a single API call with no DNS or domain verification required to get started. Custom domains come later, when you want agents sending under your own domain.
Can multiple customers share one deployment safely? Yes, with pods. Each tenant's inboxes, threads, drafts, and keys stay isolated, and per-inbox webhook routing means inbound events reach only the owning tenant's handler. For deliverability isolation, use separate domains per tenant.
Does this work with my agent framework? AgentMail drops into any framework: LangChain, Google ADK, the OpenAI Agents SDK, the Vercel AI SDK, an MCP server, or plain code calling the REST API. The email layer is independent of how your agent reasons.
What does it cost at scale? Free covers 3 inboxes and 3,000 messages. Developer is $20/month for 10 inboxes. Startup is $200/month up to 150 inboxes, then $2 per inbox. Larger fleets are priced on Enterprise. See the pricing page for current numbers.
Conclusion
Scaling agent email is not about sending more mail. It is about identity, isolation, and observability: an inbox per agent, inbound events pushed to your code, tenant data walled off with pods, reputation managed at the domain level, and an audit trail on every message. AgentMail handles that layer so your team does not rebuild a mail stack around a shared Gmail account. The free tier is enough to build the whole setup today. Start building, no credit card required.