Webhooks

Webhooks Overview

Get real-time notifications for email events.

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 nine 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.received.spam — A message was received and classified as spam (requires label_spam_read permission)
  • message.received.blocked — A message was received and matched a block list entry (requires label_blocked_read permission)
  • 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

Spam and blocked events are excluded by default. To receive them, explicitly include message.received.spam or message.received.blocked in the event_types list when creating a webhook. Messages with these labels are no longer sent as message.received.

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    event_types=["message.received", "message.sent"],
4)

Specify which events to receive; omit event_types to subscribe to all standard event types. Spam and blocked events must always be explicitly included.

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.

Payload size limit

Webhook payloads are capped at 1 MB. When a message exceeds this limit, AgentMail omits the text and html fields from the webhook payload to reduce size. All other metadata is still included. Inline images embedded in the HTML (such as base64-encoded data URIs) count toward the payload size and are a common reason for the limit being reached.

Omitted content is always available through the API. After receiving a webhook, fetch the full message to access the complete body and attachment data:

1# fetch the full message after receiving a webhook
2message = client.inboxes.messages.get(
3    inbox_id=payload["message"]["inbox_id"],
4    message_id=payload["message"]["message_id"],
5)
6text_body = message.text
7html_body = message.html
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": "<jkl012@agentmail.to>",
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": "<parent456@agentmail.to>",
30    "references": ["<ref001@agentmail.to>", "<ref002@agentmail.to>"],
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 plain-text body of the email. May be omitted when the webhook payload exceeds the 1 MB size limit. Fetch the full message via the API if this field is missing.
    • html (string): The HTML body of the email, if present. May be omitted when the webhook payload exceeds the 1 MB size limit. Fetch the full message via the API if this field is missing.
    • attachments (array<object>): A list of attachment metadata, each with its own attachment_id, filename, content_type, size, and inline status. Attachment content is not included in the webhook payload; download attachments through the API.
    • in_reply_to (string): The message_id of the email this message is a reply to, if applicable.

Copy for Cursor / Claude

Copy one of the blocks below into Cursor or Claude for complete Webhooks API knowledge in one shot.

1"""
2AgentMail Webhooks — copy into Cursor/Claude.
3
4Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
5Return 200 immediately; process payload in background.
6
7API reference:
8- webhooks.create(url, event_types?, inbox_ids?, pod_ids?, client_id?)
9- webhooks.get(webhook_id), webhooks.list(limit?, page_token?)
10- webhooks.update(webhook_id, add_inbox_ids?, remove_inbox_ids?, add_pod_ids?, remove_pod_ids?)
11- webhooks.delete(webhook_id)
12
13Events: message.received, message.received.spam, message.received.blocked, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified
14Payload: event_type, event_id, plus message/send/delivery/bounce/complaint/reject/domain. Verify with Svix (webhook.secret).
15Note: message.received.spam and message.received.blocked are excluded by default. To receive them, explicitly include them in event_types and ensure the API key has label_spam_read / label_blocked_read permissions.
16"""
17import os
18from dotenv import load_dotenv
19from agentmail import AgentMail
20
21load_dotenv()
22client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
23
24wh = client.webhooks.create(url="https://your-server.com/webhooks", event_types=["message.received"], client_id="my-webhook-v1")
25all_wh = client.webhooks.list()
26secret = client.webhooks.get(wh.webhook_id).secret

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.