Webhooks

Overview

title: “Webhooks Overview” subtitle: “Get real-time notifications for email events.” slug: overview description: “Learn how to use Webhooks to build responsive, event-driven email agents with AgentMail.”

Webhooks are the best way to get real-time information about what’s happening with your emails. Instead of constantly asking the AgentMail API if there’s a new email (a process called polling), you can register a URL, and we will send you a POST request with the details as soon as an event happens.

This event-driven approach is more efficient and allows you to build fast, responsive agents that can react instantly to incoming messages.

Why Use Webhooks?

  • Real-Time Speed: Build conversational agents that can reply to incoming emails in seconds.
  • Efficiency: Eliminates the need for constant polling, which saves you computational resources and simplifies your application logic.

Available Events

AgentMail supports seven webhook event types. When creating a webhook, you can subscribe to specific events or receive all of them. See Webhook Events for full payload details.

Message events:

  • message.received — New email received and processed in one of your inboxes
  • message.sent — Message successfully sent from your inbox
  • message.delivered — Delivery confirmed by the recipient’s mail server
  • message.bounced — Message failed to deliver and bounced back
  • message.complained — Recipient marked your message as spam
  • message.rejected — Message rejected before send (validation or policy)

Domain events:

  • domain.verified — Custom domain successfully verified

The Webhook Workflow

The process is straightforward:

1

1. Create a Webhook Endpoint

This is a public URL on your server that can accept POST requests. For local development, a tool like ngrok is perfect for creating a secure, public URL that tunnels to your local machine. Your endpoint should immediately return a 200 OK response to acknowledge receipt and process the payload in the background to avoid timeouts.

2

2. Register the Endpoint with AgentMail

You can register your URL using the AgentMail API. When you create a webhook, you’ll specify your endpoint’s URL as well as event types you want to receive.

1client.webhooks.create(
2    url="https://<your-ngrok-url>.ngrok-free.app/webhooks",
3    events=["message.received", "message.sent"],
4)

Specify which events to receive; omit events to subscribe to all event types.

3

3. AgentMail Sends Events

When an event occurs (e.g. a new message is received, a message is delivered, or a domain is verified), AgentMail sends a POST request with a JSON payload to your registered URL.

Payload Structure

When AgentMail sends a webhook, the payload includes event_type and event_id, plus event-specific data. The example below shows a message.received payload; other events use different top-level objects (send, delivery, bounce, etc.). See Webhook Events for each event’s payload shape.

Webhook Payload
1{
2  "event_type": "message.received",
3  "event_id": "evt_123abc...",
4  "message": {
5    "from_": ["sender@example.com"],
6    "organization_id": "org_abc123...",
7    "inbox_id": "inbox_def456...",
8    "thread_id": "thd_ghi789...",
9    "message_id": "msg_jkl012...",
10    "labels": ["received"],
11    "timestamp": "2023-10-27T10:00:00Z",
12    "reply_to": ["reply-to@example.com"],
13    "to": ["recipient@example.com"],
14    "cc": ["cc-recipient@example.com"],
15    "bcc": ["bcc-recipient@example.com"],
16    "subject": "Email Subject",
17    "preview": "A short preview of the email text...",
18    "text": "The full text body of the email.",
19    "html": "<html>...</html>",
20    "attachments": [
21      {
22        "attachment_id": "att_pqr678...",
23        "filename": "document.pdf",
24        "content_type": "application/pdf",
25        "size": 123456,
26        "inline": false
27      }
28    ],
29    "in_reply_to": "msg_parent456...",
30    "references": ["msg_ref1...", "msg_ref2..."],
31    "sort_key": "some-sort-key",
32    "updated_at": "2023-10-27T10:00:05Z",
33    "created_at": "2023-10-27T10:00:00Z"
34  }
35}

Field Descriptions

  • event_type (string): The event type (e.g. message.received, message.sent, message.delivered). Payload structure varies by event—see Webhook Events for each event’s shape.
  • event_id (string): A unique identifier for this specific event delivery.
  • message (object): A dictionary containing the full details of the received email message.
    • from_ (array<string>): The sender’s email address. Note the trailing underscore to avoid conflict with the Python keyword.
    • organization_id (string): The ID of your organization.
    • inbox_id (string): The ID of the inbox that received the message.
    • thread_id (string): The ID of the conversation thread.
    • message_id (string): The unique ID of this specific message.
    • labels (array<string>): Labels associated with the message (e.g., received, sent).
    • subject (string): The subject line of the email.
    • preview (string): A short plain-text preview of the email body.
    • text (string): The full plain-text body of the email.
    • html (string): The full HTML body of the email, if present.
    • attachments (array<object>): A list of attachments, each with its own attachment_id, filename, content_type, size, and inline status.
    • in_reply_to (string): The message_id of the email this message is a reply to, if applicable.

Next Steps

Webhook Events

Explore the full list of available event types and their data payloads.

Verifying Webhooks

Learn how to verify webhook signatures to secure your endpoints.

Example: Event-Driven Agent

Build a fully deployable, event-driven agent that can respond to emails in real time.