How to Build Inbound AI Email Automation 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 Build Inbound AI Email Automation with AgentMail
Inbound email automation for AI agents comes down to three things: an inbox the agent owns, an event that fires the moment a reply lands, and thread context the agent can actually read. This guide walks through setting that up with AgentMail, from provisioning your first inbox to handling inbound webhooks, replying in thread, and isolating tenants so one agent's mail never touches another's.
Introduction
Most email APIs were built for the opposite direction: an application sending mail to humans. That works fine for receipts and password resets. It falls apart when the thing on your side of the conversation is an agent that needs to receive mail, understand which conversation a message belongs to, and reply in line like a teammate.
The usual workaround is a shared human mailbox polled over IMAP, or an SMTP relay with no concept of threads. Both break in predictable ways: replies from different conversations collide, the agent borrows a person's identity, and nobody can say after the fact what the agent sent or why.
AgentMail treats email as an API primitive instead. One call provisions an inbox with no DNS setup, inbound mail arrives as a webhook or WebSocket event, and threads, drafts, labels, and attachments are first-class objects. This guide covers the full inbound path: prerequisites, setup, the webhook handler, and the mistakes that cost people the most time.
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. The getting started guide covers creating one.
- A Python or TypeScript environment with the AgentMail SDK installed.
- A publicly reachable HTTPS endpoint to receive webhooks, or a long-running process if you prefer WebSockets.
- An agent framework, if you use one. AgentMail drops into LangChain, Google ADK, the OpenAI and Claude Agent SDKs, the Vercel AI SDK, or your own loop via the MCP server.
You do not need your own domain to start. Provisioned inboxes work immediately; custom domains come later when you want mail on your own DNS.
Step-by-step
1. Provision an inbox for the agent
Create an inbox with a single API call. No domain verification, no DNS records, no waiting.
from agentmail import AgentMail client = AgentMail(api_key="YOUR_API_KEY") inbox = client.inboxes.create() print(inbox.inbox_id, inbox.address)
Code per the AgentMail SDK reference, see the API reference.
Give each agent its own inbox. A shared inbox means a shared identity and a shared audit trail, which is the failure mode this whole setup exists to avoid.
2. Decide how inbound mail reaches your agent
You have two options, and the choice is about process model, not capability:
- Webhooks. AgentMail POSTs the inbound message to your HTTPS endpoint. Best for serverless and queue-based architectures. Setup and signature verification are covered in the webhook setup and webhook verification docs.
- WebSockets. A persistent connection that streams events as they arrive. Best when your agent runs as a long-lived process and you want to skip public endpoint plumbing. See the WebSockets quickstart.
If you are unsure, start with webhooks. They are easier to debug because every event is an HTTP request you can log and replay.
3. Verify webhook signatures before parsing anything
Your endpoint will receive forged requests eventually if it is public. Verify the signature before you touch the payload. The verification doc shows the exact check for your SDK. Reject anything that fails with a 4xx, and do it before deserialization.
4. Route the event to the right agent
If you run more than one agent, or more than one customer, route on the inbox the message arrived at. Per-inbox webhook routing means each inbox's events go only to that inbox's handler. For harder isolation boundaries between customers, use pods: pod- and inbox-scoped API keys keep one tenant's inboxes, threads, and drafts separate from another's.
One correction worth internalizing early: pods isolate data, not deliverability. Sending reputation is per domain. If tenants need reputation isolation, give each tenant its own domain or subdomain per the multi-tenancy guide.
5. Read the thread, not just the message
An inbound message is rarely the whole story. Pull the thread so the agent sees the full history before it decides anything:
thread = client.inboxes.threads.get(inbox_id, thread_id)
This is what lets an agent CC'd on an ongoing conversation reply in line like a teammate instead of starting a new subject line every time.
6. Reply in thread
When the agent responds, reply against the message rather than sending a fresh email:
client.inboxes.messages.reply(inbox_id, message_id, text="Here is the answer.")
Replying in thread keeps the conversation coherent for the human on the other end and keeps your own audit history clean.
7. Log everything
Every send and receive is logged per inbox, which gives you a full audit history of what the agent did and why. Wire that log into your observability stack. When someone asks six weeks later why an agent emailed a customer, the answer should be one query away, not a memory exercise.
Common pitfalls
Polling instead of listening. If your agent polls a mailbox on a timer, every reply waits up to one full interval. Webhooks and WebSockets fire the moment mail lands. Poll only as a fallback.
Sharing one inbox across agents. One inbox means one identity, one thread history, and one blast radius. When two agents share an address, you cannot tell their actions apart and one agent's mistake is everyone's. One inbox per agent, always.
Skipping signature verification. A public webhook endpoint without verification is an unauthenticated write API into your agent. Verify first, parse second.
Assuming pods fix deliverability. Pods isolate data per tenant. Reputation follows the domain. Teams that discover this after launch end up re-provisioning domains. Decide your domain layout before you scale.
Replying outside the thread. A fresh email with a new subject breaks the conversation for the human and scatters your audit trail. Use the reply method.
Hardcoding one inbox ID. Provision inboxes programmatically and store the IDs. The free tier gives you 3 inboxes to test with; the pricing page scales to 10 on Developer and beyond from there.
Frequently Asked Questions
How fast can an agent react to an inbound email? Immediately. Inbound mail fires a webhook or WebSocket event the moment it arrives, so the agent acts on the event instead of polling a mailbox on a schedule.
Do I need my own domain before I can start? No. Provisioned inboxes work with a single API call and no DNS setup. Add a custom domain later when you want mail on your own DNS and your own sending reputation.
How do I keep one customer's email separate from another's? Use pods with pod- and inbox-scoped API keys for data isolation, and separate domains or subdomains per tenant when you also need deliverability isolation, since sending reputation is per domain.
Does this work with my agent framework? Yes. AgentMail ships integrations for LangChain, Google ADK, the OpenAI and Claude Agent SDKs, the Vercel AI SDK, and an MCP server, and the REST API works with anything else. See the quickstart for the shortest path.
Conclusion
Inbound email automation stops being an infrastructure project when email is an API: an inbox per agent provisioned in one call, inbound events pushed to your handler the moment they land, threads the agent can read before it acts, and isolation you can reason about per tenant. The whole path above is a few API calls and one webhook endpoint.
Set up your first inbox and see the webhook fire: start building. No credit card required.