Webhooks Overview

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 ten webhook event types. When creating a webhook, you can subscribe to specific events or receive all standard events. 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.received.unauthenticated — A message was received without authentication headers, so AgentMail could not verify whether it was authenticated
• 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

Updating event_types on a webhook

When you update a webhook, you can change which events it receives by sending event_types on PATCH:

• Non-empty array: Replaces the webhook’s subscribed event types in full (same idea as create: you set the whole list, not a diff). If you send only one type, the webhook will only receive that type afterward.
• Omitted or empty array: Leaves the current event types unchanged. You cannot clear all subscriptions by sending an empty list.

Subscribing to message.received.spam, message.received.blocked, or message.received.unauthenticated on update still requires the same label permissions as on create.

The Webhook Workflow

The process is straightforward:

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

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
2
message = client.inboxes.messages.get(
3
    inbox_id=payload["message"]["inbox_id"],
4
    message_id=payload["message"]["message_id"],
5
)
6
text_body = message.text
7
html_body = message.html

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
"""
2
AgentMail Webhooks — copy into Cursor/Claude.
3
4
Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
5
Return 200 immediately; process payload in background.
6
7
API 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?, event_types?)
11
- webhooks.delete(webhook_id)
12
13
Events: message.received, message.received.spam, message.received.blocked, message.received.unauthenticated, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified
14
Payload: event_type, event_id, plus message/send/delivery/bounce/complaint/reject/domain. Verify with Svix (webhook.secret).
15
Note: message.received.spam, message.received.blocked, and message.received.unauthenticated 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 for spam and blocked events.
16
On update, non-empty event_types replaces the subscribed list in full (omit or [] to leave types unchanged).
17
"""
18
import os
19
from dotenv import load_dotenv
20
from agentmail import AgentMail
21
22
load_dotenv()
23
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
24
25
wh = client.webhooks.create(url="https://your-server.com/webhooks", event_types=["message.received"], client_id="my-webhook-v1")
26
all_wh = client.webhooks.list()
27
secret = client.webhooks.get(wh.webhook_id).secret

Next Steps