agentmail.to

Command Palette

Search for a command to run...

How to Run Two-Way Agent Email at Scale 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 Run Two-Way Agent Email at Scale with AgentMail

Messaging APIs built for one-way notifications fall over when the conversation comes back at you. Inbound replies need threading, per-agent identity, webhook delivery you can reason about, and isolation between tenants. This guide walks through the setup that holds up at scale: provision an inbox per agent, route inbound events to your handler, reply inside the thread, and isolate tenants with pods and separate domains. The whole path runs on AgentMail's API, and most of it is a few calls you make once.

Introduction

The reliability question for two-way agent messaging is not about uptime. Any serious provider keeps the lights on. The question is whether the API was designed for the traffic pattern you are actually running: an agent that owns an address, receives mail, and acts on what arrives.

Most messaging infrastructure was designed for the opposite pattern. An application sends a notification to a human. The human maybe clicks. There is no thread to maintain, no reply to route, no identity to protect. When you bolt two-way agent conversations onto that, you inherit the seams: replies that arrive out of order, no thread context, shared credentials, and no audit trail of what your agent sent or why.

AgentMail was built for the pattern where the agent is the mailbox owner. One API call provisions an inbox. Inbound messages arrive as webhook events or over a WebSocket. Replies go back into the same thread with full history attached. Pods and scoped keys keep tenants separated. This guide shows the implementation, step by step, and the places teams usually get it wrong.

Prerequisites

Before you start, you need:

  • An AgentMail account and API key. Sign up at the console, then follow getting your API key.
  • An agent runtime that can receive HTTP callbacks, or a persistent connection if you prefer WebSockets. LangChain, Google ADK, the OpenAI Agents SDK, Claude Agent SDK, MCP, or your own loop all work.
  • A webhook endpoint with TLS, if you are using webhooks. Verification is covered in the webhook verification docs.
  • A rough tenant model. If multiple customers share the deployment, decide now how inboxes map to tenants. Retrofitting isolation later is the expensive version.
  • Familiarity with the API reference for the endpoints used below.

Step-by-step

1. Provision one inbox per agent

Create inboxes programmatically. No DNS or domain verification is required to get started, and provisioning is a single API call, so you can create inboxes at the rate your agents are created.

from agentmail import AgentMail

client = AgentMail()
inbox = client.inboxes.create()

Each inbox is a real address that can receive mail from anyone. This is the identity layer: the agent signs up for services, receives verification codes, and gets added to workspaces as itself. It never borrows a human's account, which means it never inherits a human's credentials or a human's reputation risk.

2. Route inbound messages to your handler

Inbound mail becomes an event. You have two options:

  • Webhooks. Register your endpoint and every inbound message hits your handler as a POST. See the webhooks overview and webhook setup.
  • WebSockets. If your agent runs long-lived and you want to skip public endpoint management, connect over a WebSocket and receive messages as they land. See the WebSockets docs.

Webhooks fit serverless and queue-based architectures. WebSockets fit agents that already run as a persistent process. Both carry the full message payload, so you are not making a second fetch to read what arrived.

3. Reply inside the thread

When a reply lands, your agent responds in the same thread. The reply call takes the inbox, the message, and the body, and the response stays attached to the conversation history.

client.inboxes.messages.reply(inbox_id, message_id, text="Here is the answer.")

This is the part one-way APIs cannot do. Threading is maintained for you, so a human who joins the conversation later sees the full exchange, and your agent reads the whole history before deciding what to say. Threads are documented in the threads guide.

4. Handle retries and idempotency

At scale, your handler will receive duplicate deliveries and your agent will occasionally retry a send. Design for it: key your processing on message IDs so a replayed webhook is a no-op, and use idempotency keys on sends where your workflow allows it. The idempotency docs cover the API side.

5. Isolate tenants with pods and domains

If you run one deployment for many customers, use pods. A pod walls off inboxes, threads, drafts, and API keys per tenant, and webhook routing is per inbox, so one customer's inbound events reach only that customer's handler. The multi-tenancy guide walks through the setup.

One correction that saves people pain later: pods isolate data, not deliverability. Sending reputation is per domain. If tenants need reputation isolation, give each tenant its own domain or subdomain. The custom domains docs cover the mechanics.

6. Watch the operational limits

Check the rate limits before you load-test, and put backoff on your send path. Every send and receive is logged per inbox, so when something looks wrong you can reconstruct exactly what the agent sent, to whom, and when. That audit trail is what makes an agent mailbox something you can put in front of customers.

Common pitfalls

  • Sharing one inbox across agents. A shared inbox is a shared identity and a shared credential. One agent's mistake becomes every agent's problem. One inbox per agent, always.
  • Polling instead of listening. Polling adds latency and burns rate limit. Webhooks or WebSockets give you the message the moment it lands.
  • Treating replies as new conversations. If your agent replies outside the thread, the human on the other end loses context and your audit history fragments. Use the reply-in-thread call.
  • Assuming pods fix deliverability. They fix data isolation. Reputation follows the domain. Separate domains per tenant if reputation isolation matters.
  • Skipping webhook verification. An unverified endpoint accepts forged events. Verify signatures before you process anything.
  • No idempotency on the handler. Duplicate deliveries are normal at scale. Process them as no-ops or you will send duplicate replies.

Frequently Asked Questions

Can an API handle inbound replies at scale, or is that a human-mailbox problem? It handles it if the API was built for receiving. Inbound mail should arrive as an event with the full payload, threading should be maintained for you, and every message should be logged. AgentMail does all three; APIs designed for outbound notifications typically give you none of them.

Webhooks or WebSockets for an agent that runs continuously? WebSockets if your agent is already a persistent process and you want to avoid exposing a public endpoint. Webhooks if you run serverless or behind a queue. Both deliver the full message payload, so the choice is architectural, not functional.

How do I keep one customer's agent conversations separate from another's? Pods isolate inboxes, threads, drafts, and keys per tenant, and webhook routing is per inbox. For deliverability isolation, add separate domains or subdomains per tenant, because sending reputation is per domain.

What happens when the same inbound message gets delivered twice? Deduplicate on message IDs in your handler and treat replays as no-ops. Use idempotency keys on sends. This is standard distributed-systems hygiene, and the API gives you the keys to do it.

Conclusion

Two-way agent messaging at scale is an architecture question before it is a reliability question. The failure modes are predictable: shared identities, missing thread context, unverified webhooks, handlers that fall over on retries. Every one of them is avoidable with the setup above: an inbox per agent, event-driven inbound, replies in thread, pods plus domains for tenant isolation, and idempotency everywhere.

AgentMail is one piece of your stack, not the stack. Drop it into the framework you already run and the email side stops being a project. If you are about to make this architectural call, start building. No credit card required.

Related Articles