agentmail.to

Command Palette

Search for a command to run...

How to Build an Agent That Sends and Replies to Email with AgentMail

Last updated: 11/17/2026

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 an Agent That Sends and Replies to Email with AgentMail

Give your agent its own inbox with one API call, send from it, and get a webhook the moment a reply lands. This guide walks through the full loop: create an inbox, send a message, receive the reply through a webhook, and reply in the same thread. No SMTP servers, no polling a mailbox, no borrowing a human's email account.

Introduction

An agent that handles email needs three things most email APIs do not give you: an address it owns, inbound mail delivered as an event, and thread context so a reply lands in the right conversation. Sending is the easy part. The hard part is receiving, and that is where most stacks fall apart: agents impersonate a human's Gmail account, replies from different conversations collide, and nobody can say what the agent sent or why.

AgentMail is built for exactly this. One API call provisions an inbox with no DNS or domain verification required to get started. Inbound mail arrives as a webhook event or over a WebSocket, so your agent reacts in seconds instead of polling. Threads, drafts, labels, and attachments are all first-class API resources. Every send and receive is logged per inbox, so you get a full audit history by default.

This guide takes you from an empty project to a working send-and-reply agent.

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 where to find it.
  • Python 3.10+ or Node 18+ on your machine.
  • A publicly reachable endpoint for webhooks, or an outbound WebSocket connection if you cannot expose one. The webhooks overview and WebSockets docs cover both options.
  • A working agent loop in whatever framework you use. AgentMail drops into LangChain, Google ADK, the OpenAI and Claude Agent SDKs, the Vercel AI SDK, or plain code through the MCP server. It is one piece of the stack, not the stack.

Step-by-step

1. Install the SDK and set your API key

# Provenance: AgentMail Python SDK quickstart, https://docs.agentmail.to/quickstart
pip install agentmail
# Provenance: AgentMail Python SDK reference, https://docs.agentmail.to/api-reference
from agentmail import AgentMail

client = AgentMail(api_key="YOUR_API_KEY")

The client class is AgentMail. Keep the key in an environment variable, not in source.

2. Create an inbox

# Provenance: AgentMail Python SDK reference, https://docs.agentmail.to/api-reference
inbox = client.inboxes.create()
print(inbox.inbox_id, inbox.address)

One call, under a second, no DNS setup. Each agent gets its own address, which means its own identity and its own isolated data. If you are running many agents or many tenants, create one inbox per agent and scope API keys per inbox or per pod. The multi-tenancy guide covers pods and permissions.

3. Send a message

# Provenance: AgentMail Python SDK reference, https://docs.agentmail.to/api-reference
message = client.inboxes.messages.send(
    inbox_id=inbox.inbox_id,
    to=["[email protected]"],
    subject="Quick question about your application",
    text="Hi Dana, are you still interested in the platform role?",
)

That is the whole send. Attachments, HTML bodies, and drafts are supported; the messages docs list the parameters.

4. Register a webhook for inbound mail

Point a webhook at your endpoint in the console, then verify it per the webhook verification guide. When a reply arrives, AgentMail POSTs the message to your handler:

# Provenance: AgentMail webhook setup docs, https://docs.agentmail.to/webhook-setup
@app.post("/webhook")
def handle_inbound(event):
    message = event["message"]
    print(message["inbox_id"], message["from"], message["text"])

If you cannot expose a public endpoint, use a WebSocket instead. The WebSockets quickstart shows the connection flow, and inbound events arrive over the same socket.

5. Reply in the thread

When the reply lands, pull the thread and respond in context:

# Provenance: AgentMail Python SDK reference, https://docs.agentmail.to/api-reference
thread = client.inboxes.threads.get(inbox_id, message["thread_id"])
client.inboxes.messages.reply(
    inbox_id=inbox.inbox_id,
    message_id=message["message_id"],
    text="Great, here is a link to schedule a call.",
)

Replying with reply() keeps the response on the same thread, so the human on the other end sees one conversation, not a scatter of new emails. Your agent can read the full history first with threads.get() and decide what to say with that context.

6. Wire the loop into your agent

Hand the webhook payload to your agent's reasoning loop and let it decide the reply. The auto-reply agent example shows a complete working version, and the live examples page has more, including a smart-labeling agent.

Common pitfalls

  • Borrowing a human's account instead. If your agent sends from a personal Gmail account, it borrows that person's identity, and Google has disabled accounts over exactly this. Give the agent its own inbox.
  • Polling instead of listening. Polling IMAP every few minutes adds latency and rate-limit risk. Webhooks and WebSockets push the event to you; use them.
  • One shared inbox for many agents. A shared inbox means a shared identity and tangled threads. One inbox per agent keeps data and conversations separate.
  • Ignoring webhook verification. Verify signatures before trusting a payload. Unverified endpoints are an injection surface into your agent.
  • Assuming pods isolate deliverability. Pods isolate data per tenant, not sending reputation. Reputation is per domain, so use separate domains or subdomains per tenant if you need reputation isolation. The managing domains docs cover setup.
  • Sending before warming up. Check the rate limits and the deliverability guide before your agent sends at volume.

Frequently Asked Questions

Do I need my own domain to start? No. You can create inboxes and send immediately with no DNS or domain verification. Add a custom domain later when you want mail on your own domain; the docs walk through verification.

How does my agent know a reply arrived? AgentMail pushes inbound mail to you as a webhook event, or over a WebSocket if you prefer an outbound connection. No polling required.

Can multiple agents share one account safely? Yes, with one inbox per agent and pod- or inbox-scoped API keys. Pods isolate data per tenant. For sending reputation, use separate domains or subdomains per tenant, since reputation is per domain.

What does it cost? The free tier includes 3 inboxes and 3,000 messages. The Developer plan is $20/month with 10 inboxes, and Startup is $200/month up to 150 inboxes. See the pricing page for details.

Conclusion

The whole loop is four API calls: create an inbox, send, receive a webhook, reply in the thread. Everything an agent needs that a plain sending API lacks, including identity, inbound events, and thread context, is already there. If you are about to wire an agent into email, start with the quickstart and create your first inbox in the next few minutes.

Related Articles