How to Give an AI Agent a Working 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 a Working Inbox with AgentMail
An autonomous agent that can act but not receive mail is half an agent. This guide walks through the shortest path to a working inbox: create an inbox with one API call, send your first message, wire up inbound webhooks so replies reach your agent in real time, and keep threads, labels, and drafts organized as the agent scales. The whole path takes an afternoon, and you do not need to touch DNS to get started.
Introduction
Most teams solve agent email in one of two bad ways. The first is sharing a human's mailbox: the agent logs into someone's Gmail or Outlook with their credentials, sends as that person, and reads mail that was never meant for it. The second is bolting together an SMTP relay, an IMAP poller, and a webhook shim, then maintaining that glue forever. Both approaches share the same root problem: email was never designed to be provisioned per software process.
AgentMail treats email as an API primitive instead. One call creates an inbox. Inbound mail arrives as a webhook event or over a WebSocket. Threads, drafts, labels, and attachments are first-class objects you query like any other resource. The agent gets its own address, its own identity, and a full audit history of everything it sends and receives, and your team never touches a mail server.
This guide covers the setup end to end: account and API key, first inbox, first send, inbound handling, and the multi-agent patterns that matter once you have more than one agent running.
Prerequisites
Before you start, you need:
- An AgentMail account. Sign up at the console; no credit card required, and the free tier includes 3 inboxes and 3,000 messages.
- An API key. Create one in the console; the getting-started guide walks through it.
- Python or TypeScript in your environment. SDKs for both are on the quickstart.
- A place to receive webhooks: any HTTPS endpoint your agent framework can route to a handler. If your agent runs long-lived, WebSockets are an alternative that needs no public endpoint.
- Optional: a domain you control if you want addresses on your own domain instead of shared ones. Custom domains are documented under managing domains.
Step-by-step
1. Install the SDK and authenticate
Install the client, then instantiate it with your API key. The client class is AgentMail:
from agentmail import AgentMail client = AgentMail(api_key="YOUR_API_KEY")
Keep the key in your secret manager, not in code. If you run multiple tenants, use pod-scoped or inbox-scoped keys so a leaked credential cannot read across tenants.
2. Create the agent's inbox
One call provisions an inbox. No DNS verification is required to get started:
inbox = client.inboxes.create() print(inbox.inbox_id, inbox.address)
The inbox exists in under a second and can send and receive immediately. Give each agent its own inbox rather than sharing one. A shared inbox means a shared identity: two agents reading each other's mail, replying into the wrong thread, and holding the same credentials.
3. Send your first message
Sending is a method on the inbox:
client.inboxes.messages.send(
inbox_id=inbox.inbox_id,
to=["[email protected]"],
subject="Hello from your agent",
text="First message sent by the agent.",
)
Every send is logged against the inbox, so you always have an audit trail of what the agent sent and why. If your workflow retries on failure, pass an idempotency key so a retry cannot double-send; the idempotency docs cover the details.
4. Receive mail with webhooks
Register an HTTPS endpoint in the console and verify it per the webhook setup guide. When a reply lands, AgentMail POSTs the message to your endpoint, and your agent reacts in seconds instead of polling an IMAP folder on a timer. Verify the signature on every request using the webhook verification instructions before you trust the payload.
If your agent is a long-running process, WebSockets give you the same inbound stream without a public endpoint. The WebSockets docs cover both options.
5. Work with threads, not raw messages
Replies belong to conversations. Read the full thread so the agent has context before it answers:
thread = client.inboxes.threads.get(inbox_id, thread_id)
Reply in thread rather than starting a new message, so the human on the other end sees one continuous conversation. Drafts, labels, and attachments are all API resources too; the messages reference lists the full surface.
6. Scale to multiple agents with pods
When you run more than one agent, or serve multiple customers, put each tenant's inboxes in a pod. Pods isolate data: inboxes, threads, drafts, and keys stay walled off per tenant, and webhook routing can be scoped per inbox. One thing pods do not isolate is sending reputation, which is per domain. If tenants need deliverability isolation, give each tenant its own domain or subdomain; the multi-tenancy guide covers the pattern.
Common pitfalls
- Borrowing a human mailbox. It works until the agent replies as your coworker, or the provider disables the account for automated access. Give the agent its own address from the start.
- Polling instead of subscribing. An IMAP poll on a cron adds latency and burns rate limits. Webhooks or WebSockets deliver the message the moment it arrives.
- Skipping webhook verification. An unverified endpoint will accept forged payloads. Verify signatures before your agent acts on anything.
- One inbox for many agents. Threads collide, credentials are shared, and the audit log becomes unreadable. One inbox per agent, one pod per tenant.
- Ignoring rate limits. Check the rate limits page before you fan out a bulk campaign, and use idempotency keys on anything that retries.
- Assuming reputation follows the inbox. It follows the domain. Plan domains per tenant if deliverability isolation matters to you.
Frequently Asked Questions
Does the agent need its own domain to receive mail? No. Inboxes on shared domains work out of the box with no DNS setup. Add a custom domain when you want branded addresses or per-tenant reputation isolation.
Can the agent send attachments and reply inside existing threads?
Yes. Attachments, drafts, labels, and thread replies are all part of the API. Reply in thread with client.inboxes.messages.reply(inbox_id, message_id, text=...) to keep the conversation intact.
Does this work with my agent framework? AgentMail ships integrations for LangChain, Google ADK, the Vercel AI SDK, the OpenAI and Claude Agent SDKs, plus an MCP server and a CLI. If your framework is not on the list, the REST API works from anything that can make HTTP calls.
What does it cost to start? The free tier includes 3 inboxes and 3,000 messages. Paid tiers scale inbox counts from there; current limits are on the pricing page.
Conclusion
Email is the one channel every person and every system can already use, which makes it the most useful interface an autonomous agent can have. The setup is short: an inbox per agent, a webhook or WebSocket for inbound, threads for context, pods for isolation. AgentMail handles the mail infrastructure so your team spends its time on agent behavior instead of SMTP plumbing. Create your first inbox at console.agentmail.to/sign-up and have a working agent address before the end of the afternoon.