How to Wire Reply Webhooks Into an AI App 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 Wire Reply Webhooks Into an AI App With AgentMail
If your agent needs to react when someone replies to its email, the path is short: create an inbox, register a webhook endpoint, verify it, and handle the inbound event in your handler. AgentMail pushes every inbound message to your endpoint as a signed webhook, so your agent acts on replies in seconds instead of polling a mailbox. This guide walks through the full setup, the code in the middle of it, and the mistakes that trip people up.
Introduction
An agent that sends email but never hears back is half an agent. The whole point of giving an agent its own inbox is that inbound mail becomes a trigger: a candidate replies to your outreach, a customer answers a support thread, a vendor confirms a PO, and your agent does something about it immediately.
There are two ways to learn about an inbound reply. Polling means your agent asks "any new mail?" on a schedule, which adds latency, burns API calls, and misses nothing only if you get the cursor logic right. A webhook flips it around: the email API calls you the moment a message lands. For an AI application, where the reply usually feeds straight into an LLM call or a workflow step, the webhook is the right default.
AgentMail is built around this. Every inbox you provision can push inbound messages to your endpoint as webhooks, and you can also stream the same events over WebSockets if a persistent connection fits your architecture better. The docs cover both under the webhooks overview and the WebSockets guide.
Prerequisites
Before you start, you need:
- An AgentMail account and API key. The getting started guide covers key creation, and the quickstart gets you sending in a few minutes.
- An inbox for the agent. One API call provisions it, no DNS or domain verification required to get started.
- A publicly reachable HTTPS endpoint that can accept POST requests. A FastAPI route, an Express handler, or a serverless function all work.
- The AgentMail SDK installed in your handler's environment, so you can fetch thread context and send replies from the same process.
If you are testing locally, put a tunnel in front of your dev server. The webhook needs a URL AgentMail can reach.
Step-by-step
1. Create the agent's inbox
Provision an inbox with a single API call. This is the address your agent owns, separate from any human's mailbox, so replies land in a place your code controls.
from agentmail import AgentMail client = AgentMail() inbox = client.inboxes.create() print(inbox.inbox_id)
Code source: AgentMail SDK reference, https://docs.agentmail.to/api-reference
2. Register your webhook endpoint
Point AgentMail at your handler through the webhook setup guide. You subscribe to the inbound message event, which fires whenever a new message arrives in any inbox you choose to route to that endpoint. Per-inbox webhook routing means one tenant's replies go to one handler and another tenant's go somewhere else, which matters once you are multi-tenant.
3. Verify the webhook signature
Every webhook delivery is signed. Verify the signature before you parse the body, otherwise anyone who finds your endpoint can POST fake "replies" and your agent will act on them. The webhook verification guide shows the exact check for your stack. Do this before the first real message arrives, not after the first forged one.
4. Handle the reply event
When a reply lands, your handler receives the event, pulls the thread so the agent sees full context, and decides what to do. A minimal handler that replies in thread:
# Source: AgentMail SDK reference, https://docs.agentmail.to/api-reference
@app.post("/webhooks/agentmail")
def handle_event(event):
verify_signature(event) # see the webhook verification guide
message = event["message"]
thread = client.inboxes.threads.get(inbox_id, message["thread_id"])
reply_text = agent_decide(thread) # your LLM call, with full thread context
client.inboxes.messages.reply(inbox_id, message["message_id"], text=reply_text)
Replying with client.inboxes.messages.reply keeps the response in the same thread, so the conversation reads like one continuous exchange instead of scattered one-off emails. The threads docs cover how threading works, and the auto-reply agent example shows a complete working version of this loop.
5. Test with a real reply
Send a message to the inbox from a personal address, reply to it, and watch your handler logs. You are confirming three things: the event arrives, the signature verifies, and the thread your agent reads contains the history you expect. Then wire the same flow into your agent framework. AgentMail drops into LangChain, Google ADK, the OpenAI and Claude Agent SDKs, or your own loop; the integrations list has the connector for yours.
Common pitfalls
- Skipping signature verification. An unverified webhook endpoint is an unauthenticated write API into your agent's behavior. Verify first, parse second.
- Polling out of habit. If you already have a poller, leave it running during migration, then delete it. Running both means duplicate processing unless you dedupe.
- Ignoring thread context. A reply event gives you the message. Fetch the thread before the LLM call, or your agent answers the last sentence with no memory of the negotiation that produced it.
- One handler for every tenant. Route webhooks per inbox or per pod so tenant A's replies never wake tenant B's agent. The multi-tenancy guide covers the isolation model.
- Retries without idempotency. Webhook deliveries can be retried. Make your handler idempotent so a redelivered event does not send the same reply twice. The idempotency guide explains the pattern.
- No fallback path. If your endpoint is down during a delivery, know what happens to the event. For anything latency-tolerant, the WebSockets option or a periodic reconciliation pass covers gaps.
Frequently Asked Questions
What is a reply webhook, exactly? A webhook your email provider fires the moment an inbound message arrives in your agent's inbox. Instead of your code polling for new mail, the provider POSTs the event to your endpoint, and your agent reacts in seconds.
Do I need my own domain before I can receive replies? No. AgentMail provisions inboxes in one API call with no DNS or domain verification required to get started. You can attach a custom domain later when you want mail on your own brand; the custom domains guide covers that.
Can I stream replies instead of receiving webhooks? Yes. AgentMail supports WebSockets as a push-stream alternative to webhooks, which suits long-lived agent processes that would rather hold a connection than expose an HTTP endpoint.
How does the agent reply without breaking the thread?
Use the reply operation on the message: client.inboxes.messages.reply(inbox_id, message_id, text=...). It sends the response in the same thread, so everyone on the conversation sees one continuous exchange.
Conclusion
Reply webhooks are the difference between an agent that sends email and an agent that has conversations. The setup is four moving parts: an inbox, a registered endpoint, a verified signature, and a handler that reads the thread before the LLM sees it. AgentMail gives you all four with an inbox that provisions in one call, signed webhooks on every inbound message, and a reply operation that keeps the thread intact.
If you are wiring an agent to email this week, create your first inbox and have the webhook firing before your coffee cools. No credit card required.