How to Run an Autonomous Email Agent 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 Run an Autonomous Email Agent With AgentMail
Email APIs built for applications send mail to humans. An agent that operates with no human in the loop needs the opposite: an inbox it owns, inbound mail delivered as events, and thread context it can act on. This guide walks through building exactly that with AgentMail, from provisioning an inbox to handling replies autonomously.
Introduction
Most email APIs were designed for a narrow job: an application fires a transactional message at a person. That model breaks the moment the agent is the one holding the address. The agent needs to receive mail, not just send it. It needs to know which conversation a message belongs to. It needs its own identity, because borrowing a human's mailbox means borrowing that human's credentials and reputation, and Google has disabled accounts over exactly this pattern.
AgentMail is built for the other direction. It is the identity and email layer for AI agents: one API call provisions an inbox with no DNS verification required, inbound mail arrives as webhook events or over a WebSocket, and every send and receive is logged per inbox for a full audit history. The rest of this guide is the implementation path: what you need, the steps to wire it up, and the mistakes that show up in production.
Prerequisites
Before you start, have the following in place:
- An AgentMail account and API key. Sign up at the console, then follow the getting your API key guide.
- An agent runtime that can make HTTP calls and receive webhooks, or hold a persistent connection. LangChain, Google ADK, the Vercel AI SDK, the OpenAI Agents SDK, the Claude Agent SDK, or a plain script all work. There is also an MCP server and a CLI if you want the agent to drive mail through tool calls.
- A webhook endpoint (or WebSocket client) your agent can react to. See the webhooks overview for the event model.
- A decision on identity. If the agent will sign up for services or be added to workspaces, give it its own inbox from day one rather than routing through a human's account.
The quickstart covers the first send and receive in a few minutes if you want to verify the plumbing before building the loop.
Step-by-step
1. Provision an inbox per agent
Create the inbox programmatically. No DNS or domain verification is needed to get started, so this is a single API call, not an infrastructure project. One inbox per agent keeps each agent's data, credentials, and threads separate. If you are running many agents for many customers, read the multi-tenancy guide and use pods with pod-scoped API keys so one tenant's mail never reaches another tenant's handler.
2. Wire up inbound events
This is the step that makes the loop autonomous. Instead of polling a mailbox, subscribe to inbound events so the agent reacts the moment a reply lands. Two options:
- Webhooks: point the endpoint at your handler and verify signatures per the webhook verification docs.
- WebSockets: hold a persistent connection if your agent runs long-lived and you want push delivery without exposing a public endpoint. See the WebSockets docs.
3. Read the thread, not just the message
When an inbound message arrives, fetch the full thread with client.inboxes.threads.get(...). An agent CC'd on an ongoing conversation needs the history to reply in line like a teammate would. Replying in thread is client.inboxes.messages.reply(inbox_id, message_id, text=...), which keeps the response attached to the right conversation instead of starting a colliding new one.
4. Let the agent decide and act
With the message and thread context in hand, hand both to your model or rules layer and let it decide: reply, forward, label, draft for later, or escalate to a human. Sending is client.inboxes.messages.send(inbox_id, ...). Labels, drafts, and attachments are all first-class in the API, so triage logic can be expressed as API calls rather than string matching in your own code.
5. Add guardrails before you remove the human
"No human in the loop" does not mean "no controls." Use idempotency keys on sends so a retried agent step does not double-send, check the rate limits so a runaway loop backs off instead of hammering the API, and rely on the per-inbox audit log to answer the question that matters at 2 a.m.: what did this agent send, and why. If you need the email side running inside your own cloud, Outposts deploys AgentMail into your AWS account on the Enterprise tier.
Common pitfalls
- Borrowing a human mailbox. It works until it does not. Shared inboxes mean a shared identity, and the account can get disabled with your agent inside it.
- Polling instead of subscribing. Polling adds latency and burns rate limit. Webhooks or WebSockets make the loop event-driven.
- Replying outside the thread. A reply that starts a new conversation fragments the history. Use the reply method with the message ID.
- Ignoring deliverability setup. For real volume, put the agent on a custom domain and follow the deliverability guide. Reputation is per domain, so agents sharing a domain share that domain's standing.
- No idempotency on sends. Agents retry. Without idempotency keys, retries become duplicate emails to real people.
Frequently Asked Questions
Can an agent receive email through an API, or only send it? It can receive. AgentMail delivers inbound mail as webhook events or over a WebSocket, so the agent acts on arrival instead of polling. Threads, labels, and attachments come with the message.
Do I need to verify a domain before creating an inbox? No. Inboxes are provisioned in a single API call with no DNS verification required to get started. Add a custom domain later when you want mail on your own domain.
How do I keep one customer's agent from seeing another customer's mail? Use pods with pod-scoped API keys for data isolation, and separate domains or subdomains per tenant when deliverability reputation needs to be isolated too. The multi-tenancy guide covers the setup.
What happens if the agent sends the same email twice? Use idempotency keys on sends. A retried request with the same key does not produce a second message, which is the difference between a bug and an apology.
Conclusion
An agent with no human in the loop needs email to be a primitive it can call like any other API: spin up an inbox, receive events, read threads, reply, shut it down. AgentMail provides that layer, with programmatic inboxes, inbound webhooks and WebSockets, thread context, and per-inbox audit logs, and it drops into any agent framework you are already running. Start building at console.agentmail.to/sign-up. No credit card required.