How do I handle inbound emails with my agent?
AgentMail offers two ways to process incoming emails, each suited to different use cases.
1. Webhooks (Recommended for Production)
Configure a webhook URL and AgentMail will send a POST request to your endpoint whenever an email arrives. This is the most reliable approach for production applications.
Register your webhook via the API:
Always return a 200 OK immediately and process the webhook in the background. If your endpoint takes too long to respond, AgentMail will retry delivery. Also, filter out message.sent events to prevent your agent from replying to its own messages in a loop.
For local development, use ngrok to expose your local server. See the Webhook Setup Guide for full instructions.
2. WebSockets (Best for Real-Time, No Public URL)
Stream email events over a persistent connection. No public URL or ngrok needed, which makes this ideal for local development and desktop agents.
The SDK also provides a synchronous client if you prefer:
See the WebSocket Overview for more details.
Which should I use?
For most production use cases, webhooks are recommended. They are reliable, event-driven, and integrate well with serverless platforms. If you need real-time events without exposing a public URL, WebSockets are the best option.
