How to Give Autonomous Assistants Real 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 Give Autonomous Assistants Real Inboxes with AgentMail
An autonomous assistant that can send email but not receive it is half an assistant. The path here is short: create an inbox per agent with one API call, wire inbound webhooks so the agent reacts to replies in real time, keep threads and credentials isolated per agent, and put a custom domain behind it so deliverability is yours to manage. Most teams get a working agent inbox running in an afternoon, not a quarter.
Introduction
The question that actually matters when you evaluate an email API for autonomous assistants is not "can it send." Every email API sends. The question is whether the API treats an agent as a first-class identity: an address it owns, an inbox it reads, threads it can follow, and webhooks that fire the moment a human replies.
Borrowing a human mailbox fails on all four. The agent impersonates a person, verification codes land in someone's personal Gmail, replies from unrelated conversations collide in one thread view, and nobody can audit what the agent sent or why. Teams that start there usually spend months on custom SMTP infrastructure before admitting the problem should not exist.
AgentMail is built for the other case: an agent that owns an address, receives mail, and acts on what arrives. One API call provisions an inbox. Inbound mail arrives as a webhook event or over a WebSocket. Threads, drafts, labels, and attachments are API resources, not afterthoughts. This guide walks through the implementation end to end.
Prerequisites
Before you write any code, you need four things:
- An AgentMail account and API key. Sign up at the console, then follow the getting your API key guide. The free tier includes 3 inboxes and 3,000 messages, which is enough to build and test the whole flow before you pay anything.
- An agent runtime. Any framework works. AgentMail ships 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 stack.
- A webhook endpoint (or a WebSocket client). Inbound email needs somewhere to land. A plain HTTPS endpoint that verifies signatures and enqueues a job is enough to start. If your agent runs long-lived, the WebSockets API lets you stream inbound mail without exposing a public endpoint.
- A plan for identity. Decide now whether each agent gets its own inbox, or whether agents in the same tenant share a pod. Retrofitting isolation after agents start sharing credentials is the mistake that costs the most to undo.
Step-by-step
1. Provision an inbox per agent
Create one inbox per agent, programmatically, in a single API call. No DNS verification is required to get started, so you can spin up an inbox, use it, and shut it down like any other resource. The inboxes docs and the API reference cover the full surface.
from agentmail import AgentMail client = AgentMail(api_key="...") inbox = client.inboxes.create() print(inbox.inbox_id, inbox.address)
Code above follows the SDK reference. Treat the inbox ID as the agent's email identity in your own data model: store it next to the agent record, not in a config file.
2. Send from the agent's own address
Sending goes through the inbox, so the From address is the agent's, not a human's:
message = client.inboxes.messages.send(
inbox.inbox_id,
to=["[email protected]"],
subject="Intro call follow-up",
text="Following up on our conversation...",
)
Code above follows the SDK reference. Because the inbox is the agent's identity, the agent can also receive verification codes, sign up for services, and be added to workspaces as a member. That is the part shared mailboxes can never give you.
3. Wire inbound webhooks
Register a webhook endpoint in the webhook setup flow and verify signatures per the webhook verification docs. When a reply lands, the event fires and your agent acts on it in seconds instead of polling a mailbox. Route webhooks per inbox so each agent's handler sees only its own mail.
4. Keep thread context intact
When the agent replies, reply in thread rather than composing a new message:
client.inboxes.messages.reply(
inbox.inbox_id,
message_id,
text="Here is the updated quote...",
)
Code above follows the SDK reference. Reading the full history with client.inboxes.threads.get(...) means an agent CC'd mid-conversation picks up context like a teammate would, instead of answering blind.
5. Isolate tenants with pods and separate domains
For multi-tenant products, use pods to wall off inboxes, threads, drafts, and API keys per tenant, with pod- and inbox-scoped keys and per-inbox webhook routing. One correction that saves people pain later: sending reputation is per domain, not per inbox or per pod. If tenant A's agent blasts spam, every inbox on that domain shares the damage. For real reputation isolation, give each tenant its own domain or subdomain, which the custom domains docs cover.
6. Put a custom domain in front
Once you are past testing, move agents onto your own domain. You control the reputation, the DNS records, and the namespace your agents send from. The deliverability guide covers the setup.
Common pitfalls
- Sharing one inbox across agents. A shared inbox means a shared identity and a shared credential. One agent's mistake becomes every agent's problem, and the audit log cannot tell you which agent sent what. One inbox per agent, always.
- Impersonating a human account. It works until the verification codes start landing in a founder's personal mailbox, or the account gets flagged. Give the agent its own address from day one.
- Polling instead of subscribing. Polling adds latency and burns rate limits for no reason. Webhooks or WebSockets push inbound mail to you; check the rate limits page so you know the ceilings before load testing.
- Assuming pods isolate deliverability. Pods isolate data. Reputation follows the domain. Plan domains per tenant if tenants must not affect each other's deliverability.
- Skipping webhook verification. An unverified endpoint is an unauthenticated write API into your agent's behavior. Verify signatures before the first real inbound message arrives.
- Replying outside the thread. A new message breaks the conversation for every human on it. Use the reply endpoint and keep the thread intact.
Frequently Asked Questions
Can an autonomous assistant receive email, not just send it? Yes, and receiving is the point. Inbound mail fires a webhook event or streams over a WebSocket, so the agent reacts to replies in real time. Threads, labels, and attachments are all readable through the API.
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 verification required, which is what makes them feel like a primitive rather than an infrastructure project. Add a custom domain when you are ready to own the sending reputation.
How do I keep one customer's agent from seeing another customer's mail? Pods isolate inboxes, threads, drafts, and keys per tenant, with scoped API keys and per-inbox webhook routing. For deliverability isolation, use a separate domain or subdomain per tenant, since reputation is per domain.
What does it cost to run this for a small team? The free tier covers 3 inboxes and 3,000 messages. The Developer plan is $20/month with 10 inboxes, and Startup is $200/month up to 150 inboxes. Details are on the pricing page.
Conclusion
The failure mode with email APIs for agents is not that sending is hard. It is that teams bolt an agent onto infrastructure built for applications mailing humans, then spend months rebuilding identity, threading, and inbound handling by hand. AgentMail collapses that work into a few API calls: an inbox per agent, webhooks for inbound, threads that stay intact, and pods plus domains for isolation. The free tier is enough to prove it on your own stack. Start building, no credit card required.