agentmail.to

Command Palette

Search for a command to run...

How to Trigger Your Agent on Inbound 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 Trigger Your Agent on Inbound Email with AgentMail

An inbound email should be an event, not a mailbox you poll. With AgentMail, you create an inbox with one API call, register a webhook URL, and every message that lands fires an HTTP POST to your handler with the full message body, thread context, and attachments included. This guide walks through the whole path: getting an API key, provisioning an inbox, registering and verifying the webhook, handling the payload, and replying in thread. Most teams have a working end-to-end loop in an afternoon.

Introduction

Most email APIs were built for the opposite direction: your application sends mail to humans. Receiving was an afterthought, so teams wiring agents to act on inbound mail end up polling IMAP, parsing raw MIME, or impersonating a human's Gmail account and borrowing that human's identity along with it.

AgentMail is built for the agent that owns an address and acts on what arrives. An inbox is provisioned programmatically in a single API call, no DNS verification required to start. Inbound messages arrive as webhook events (or over WebSockets if you prefer a persistent connection), with the message body in the payload, so your handler has everything it needs without a second fetch. Threads, labels, drafts, and attachments are all first-class API resources, which means your agent can reply in line like a teammate instead of firing off orphaned messages.

The rest of this guide is the concrete setup. Every step maps to a page in the AgentMail docs.

Prerequisites

Before you start, you need:

  • An AgentMail account. Sign up at the console, no credit card required. The free tier includes 3 inboxes and 3,000 messages, which is enough to build and test the whole loop.
  • An API key. Create one in the console; the getting your API key page walks through it. Store it in your secrets manager, not in the repo.
  • A publicly reachable HTTPS endpoint that accepts POST requests. A FastAPI route, an Express handler, or a serverless function all work.
  • A supported SDK or plain HTTP. Python and TypeScript SDKs are available, and there is an MCP server and a CLI if you would rather drive things from a terminal while you prototype.

Step-by-step

1. Create an inbox

One API call provisions an inbox. No domain setup, no DNS records, nothing to verify before your first test message.

from agentmail import AgentMail

client = AgentMail(api_key="YOUR_API_KEY")
inbox = client.inboxes.create()
print(inbox.inbox_id, inbox.address)

Code from the AgentMail SDK reference, see the Inboxes docs.

You can pass a specific username and domain if you want a predictable address, or let the API generate one. For production agents on your own brand, add a custom domain later; it is not a blocker for getting the webhook loop working.

2. Register your webhook URL

In the console or via the API, register the HTTPS endpoint that should receive inbound events. The webhook setup page covers registration and the event types you can subscribe to. You can route webhooks per inbox, which matters once you run more than one agent: each inbox's events go to the handler that owns it.

3. Verify the webhook signature

Every delivery is signed. Verify the signature before you trust the payload, otherwise anyone who discovers your URL can POST fake messages into your agent's brain. The webhook verification page has the exact verification code for your stack. Do this in step 3, not as a cleanup task after launch.

4. Handle the payload

When a message arrives, your handler receives the event with the sender, subject, body, thread ID, and attachments. Because the body is included, there is no second fetch to make before your agent can act.

@app.post("/webhooks/agentmail")
def handle_event(event):
    message = event["message"]
    thread = client.inboxes.threads.get(inbox.inbox_id, message["thread_id"])
    reply_text = my_agent.decide(thread)
    client.inboxes.messages.reply(
        inbox.inbox_id, message["message_id"], text=reply_text
    )

Code from the AgentMail SDK reference, see the API reference.

Replying with messages.reply keeps the response inside the same thread, so the human on the other end sees one conversation, not a new thread per reply.

5. Return 2xx fast, process async

Acknowledge the webhook with a 200 quickly, then hand the actual agent work to a queue or background task. If your handler blocks on a slow LLM call, you risk timeouts and retries on the delivery side. The webhooks overview describes delivery behavior; design your handler around it.

6. Test the loop end to end

Send a real email to the inbox address from your personal account. Watch the webhook fire, confirm the signature check passes, confirm the reply lands in the same thread. The quickstart covers a minimal working version of this loop if you want a reference implementation first.

Common pitfalls

  • Skipping signature verification. An unverified webhook endpoint is an unauthenticated write API into your agent. Verify the signature on every request, per the verification docs.
  • Blocking in the handler. A 30-second model call inside the webhook handler causes retries and duplicate processing. Acknowledge, then process.
  • Not handling duplicates. Retries happen. Key your processing on the message ID so a redelivered event is a no-op. The idempotency page covers the API-side patterns.
  • Polling out of habit. If you find yourself writing an IMAP poller next to your webhook, delete the poller. Webhooks (or WebSockets) are the intended trigger path.
  • Sharing one inbox across agents. One inbox per agent keeps identities, threads, and credentials separate. For multi-tenant setups, use pods for data isolation, and separate domains or subdomains per tenant when deliverability reputation needs to be isolated too.
  • Ignoring rate limits in tests. A test suite that fires hundreds of sends can hit rate limits. Space out integration tests or mock the send path.

Frequently Asked Questions

Does the webhook payload include the message body? Yes. The payload carries the sender, subject, body, thread ID, and attachments, so your handler can act without a second API call. See the webhooks overview.

Can I use WebSockets instead of webhooks? Yes. AgentMail supports both inbound webhooks and WebSockets. WebSockets suit long-lived processes that want a persistent stream; webhooks suit stateless HTTP handlers. The WebSockets quickstart covers the alternative path.

Do I need my own domain before I can receive mail? No. Inboxes are provisioned in a single API call with no DNS verification required to get started. Add a custom domain when you want addresses on your own brand.

How do I isolate events per customer or per agent? Route webhooks per inbox, and scope API keys per inbox or per pod. For multi-tenant data isolation, see the multi-tenancy guide. For deliverability reputation isolation, use separate domains or subdomains per tenant.

Conclusion

The whole loop is small: create an inbox, register a verified webhook, handle the payload, reply in thread. What it replaces is the part nobody should be building in 2026: IMAP polling, MIME parsing, or an agent borrowing a human's inbox and identity. One API call creates an inbox. The webhook fires when a reply lands. Your agent does the rest.

Drop AgentMail into any agent framework, LangChain, CrewAI, Google ADK, or your own, and the email side becomes a primitive you call like any other API. Start building, no credit card required.

Related Articles