How to Give an AI Agent Its Own Inbox 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 Give an AI Agent Its Own Inbox with AgentMail
An agent that acts over email needs an address it owns: one inbox per agent, provisioned with a single API call, with inbound webhooks instead of polling, threads it can read and reply in, and an audit log of everything it sent. This guide walks through the whole setup: getting an API key, creating the inbox, sending and receiving, wiring webhooks, and scaling to many agents with pods and domains. The total work is an afternoon, not an SMTP project.
Introduction
Most teams start by pointing their agent at a human's mailbox. That works until it does not. The agent is now impersonating a person, reading mail that is not its business, and sending from an account that can get disabled. There is no threading context you can trust, no clean way to tell which agent touched which thread, and no observability into what went out or why.
The alternative is to treat email as an API primitive. Spin up an inbox, use it, shut it down. AgentMail is built for exactly that: it is the identity and email layer for AI agents, giving any agent its own inbox, its own domain, and a full history of everything it sends and receives. This guide shows how to wire it into an agent in a few steps.
Prerequisites
Before you start, you need:
- An AgentMail account. Sign up at the console. No credit card required.
- An API key. The getting your API key guide covers creating and scoping one.
- A Python or TypeScript environment with the AgentMail SDK installed.
- An agent framework, if you use one. There are integrations for LangChain, Google ADK, the Vercel AI SDK, the OpenAI Agents SDK, the Claude Agent SDK, and an MCP server, or you can call the REST API directly from your own code.
- A webhook endpoint (or a WebSocket client) if your agent should react to inbound mail in real time.
The quickstart covers the first send in a few minutes if you want to follow along there instead.
Step-by-step
1. Create an inbox for the agent
One API call provisions an inbox. No DNS setup or domain verification is required to get started, so you can be sending within a minute of getting your key.
from agentmail import AgentMail client = AgentMail() # reads AGENTMAIL_API_KEY from the environment inbox = client.inboxes.create() print(inbox.inbox_id, inbox.address)
Provenance: matches the AgentMail SDK reference; see the API reference.
Give each agent its own inbox. A shared inbox means a shared identity, and it makes debugging "who sent this" impossible.
2. Send your first message
Sending is a method on the inbox:
client.inboxes.messages.send(
inbox_id=inbox.inbox_id,
to=["[email protected]"],
subject="Your invoice is ready",
text="Invoice #1042 is attached.",
)
Provenance: matches the SDK reference for client.inboxes.messages.send.
Attachments, labels, drafts, and lists are all part of the same surface. The inboxes docs and messages docs cover each.
3. Receive mail as events, not polls
When a reply lands, AgentMail fires a webhook to your endpoint. Your agent acts on the event immediately instead of polling a mailbox on a schedule. Set up the endpoint with the webhook setup guide and verify signatures per the webhook verification docs. If you would rather hold a persistent connection, WebSockets give you the same inbound stream without a public endpoint.
4. Reply in thread with full context
An agent CC'd on a thread can read the whole history and reply in line, like a teammate. Threads are a first-class object:
thread = client.inboxes.threads.get(inbox_id, thread_id) client.inboxes.messages.reply(inbox_id, message_id, text="On it.")
Provenance: matches the SDK reference for client.inboxes.threads.get and client.inboxes.messages.reply.
This is the difference between an agent that sends notifications and one that holds a conversation.
5. Scale to many agents safely
When you run dozens or hundreds of agents, isolate them:
- Pods wall off data per tenant: inboxes, threads, drafts, and API keys stay separate. See the multi-tenancy guide.
- Separate domains or subdomains per tenant isolate sending reputation, since reputation is per domain, not per inbox. The custom domains docs cover setup.
- Scoped API keys limit what each agent can touch.
Every send and receive is logged per inbox, so you always have the audit trail.
Common pitfalls
- Borrowing a human's account. It works in a demo and fails in production: shared credentials, mixed threads, and an account that can be disabled over exactly this behavior.
- Polling instead of subscribing. Polling adds latency and burns rate limits. Webhooks or WebSockets are the right default for inbound mail.
- One inbox for every agent. You lose isolation and your audit log becomes guesswork. One inbox per agent, always.
- Assuming pods fix deliverability. Pods isolate data. Reputation follows the domain, so use separate domains or subdomains when tenants must not share a sending reputation.
- Skipping webhook verification. Verify signatures before trusting a payload, or anyone who finds your endpoint can inject mail events into your agent.
Frequently Asked Questions
Do I need my own domain to start? No. You can create inboxes and send immediately with no DNS work. Add a custom domain later when you want mail from your own domain; the docs walk through verification.
How fast can an agent react to an inbound email? Immediately. Inbound mail triggers a webhook event (or arrives over a WebSocket), so the agent handles the reply the moment it lands rather than on a poll interval.
How do I keep one customer's agent data separate from another's? Pods isolate inboxes, threads, drafts, and keys per tenant, and inbox-scoped webhooks route events to the right handler. For sending reputation, use a separate domain or subdomain per tenant.
What does it cost to try this? The free tier includes 3 inboxes and 3,000 messages, and the Developer plan is $20 per month for 10 inboxes. Current limits are on the pricing page.
Conclusion
Email is the one channel every person and every system can reach, and an agent that owns its own inbox can use it like any other API: provision an address in one call, send, receive events, reply in thread, and hand your team a complete audit log. The steps above are the whole integration. If you are about to build this on a general-purpose mail API designed for humans, build it on one designed for agents instead. Start building.