Webhook Events

As mentioned in the overview, webhooks allow us to create event-driven applications.

AgentMail supports multiple event types that allow you to build comprehensive, event-driven workflows for your email agents.

All webhook payloads follow the same basic structure:

1 {
2   "type": "event",
3   "event_type": "event.name",
4   "event_id": "evt_123abc..."
5   // ... event-specific data object
6 }

Parsing events with SDKs

The AgentMail SDKs export typed classes for each webhook payload shape, so you can parse raw payloads into fully typed objects.

1 import { serialization } from "agentmail";
2 
3 async function handleWebhook(payload: Record<string, unknown>) {
4   const eventType = payload.event_type;
5   const receivedEventTypes = [
6     "message.received",
7     "message.received.spam",
8     "message.received.blocked",
9     "message.received.unauthenticated",
10   ];
11 
12   if (receivedEventTypes.includes(String(eventType))) {
13     const event = await serialization.events.MessageReceivedEvent.parse(payload);
14     // access typed fields
15     console.log(event.message.subject);
16     console.log(event.thread.messageCount);
17   } else if (eventType === "message.sent") {
18     const event = await serialization.events.MessageSentEvent.parse(payload);
19     console.log(event.send.recipients);
20   } else if (eventType === "message.bounced") {
21     const event = await serialization.events.MessageBouncedEvent.parse(payload);
22     console.log(event.bounce.type);
23   } else if (eventType === "message.delivered") {
24     const event = await serialization.events.MessageDeliveredEvent.parse(payload);
25     console.log(event.delivery.recipients);
26   } else if (eventType === "message.complained") {
27     const event = await serialization.events.MessageComplainedEvent.parse(payload);
28     console.log(event.complaint.type);
29   } else if (eventType === "message.rejected") {
30     const event = await serialization.events.MessageRejectedEvent.parse(payload);
31     console.log(event.reject.reason);
32   } else if (eventType === "domain.verified") {
33     const event = await serialization.events.DomainVerifiedEvent.parse(payload);
34     console.log(event.domain.status);
35   }
36 }

Copy for Cursor / Claude

Copy one of the blocks below into Cursor or Claude for webhook event parsing in one shot.

1 """
2 AgentMail Webhook Events — copy into Cursor/Claude.
3 
4 Parse typed events: MessageReceivedEvent (message.received, message.received.spam, message.received.blocked, message.received.unauthenticated),
5 MessageSentEvent (send), MessageBouncedEvent (bounce), MessageDeliveredEvent (delivery), MessageComplainedEvent (complaint),
6 MessageRejectedEvent (reject), DomainVerifiedEvent (domain).
7 Only message.received* includes full message+thread; others have send/delivery/bounce/complaint/reject/domain.
8 Note: message.received.spam and message.received.blocked require label_spam_read / label_blocked_read permissions.
9 message.received.unauthenticated must be explicitly included in event_types.
10 """
11 from agentmail import (
12   MessageReceivedEvent,
13   MessageSentEvent, MessageBouncedEvent,
14   MessageDeliveredEvent, MessageComplainedEvent, MessageRejectedEvent, DomainVerifiedEvent,
15 )
16 
17 def handle(payload: dict):
18   t = payload.get("event_type")
19   if t in {"message.received", "message.received.spam", "message.received.blocked", "message.received.unauthenticated"}: e = MessageReceivedEvent(**payload); print(e.message.subject, e.thread.message_count)
20   elif t == "message.sent": e = MessageSentEvent(**payload); print(e.send.recipients)
21   elif t == "message.bounced": e = MessageBouncedEvent(**payload); print(e.bounce.type)
22   elif t == "message.delivered": e = MessageDeliveredEvent(**payload)
23   elif t == "message.complained": e = MessageComplainedEvent(**payload)
24   elif t == "message.rejected": e = MessageRejectedEvent(**payload); print(e.reject.reason)
25   elif t == "domain.verified": e = DomainVerifiedEvent(**payload); print(e.domain.status)

Message Events

`message.received`

Description: Triggered whenever a new email is successfully received and processed in one of your Inboxes. This is the most common trigger to kick off agent workflows.
Example use-case: Kick off a internal workflow when a customer complaint email hits the support inbox

Something here to notice is message.received and its filtered variants are the only webhook events that include both the metadata on the Thread and the Message in the payload. Other event types send only metadata on the event. Let us know if you need metadata on other event types by emailing support@agentmail.cc

The text and preview fields may be absent when the original email only contains HTML with no plain-text part. This is common with forwarded emails from clients like Gmail and Outlook. When handling incoming messages, always check for html as the primary content source and treat text as optional.

1 {
2   "type": "event",
3   "event_type": "message.received",
4   "event_id": "evt_123abc",
5   "message": {
6     "inbox_id": "inbox_456def",
7     "thread_id": "thd_789ghi",
8     "message_id": "<abc123@agentmail.to>",
9     "labels": ["received"],
10     "timestamp": "2023-10-27T10:00:00Z",
11     "from": "Jane Doe <jane@example.com>",
12     "to": ["Support Agent <support@agentmail.to>"],
13     "subject": "Question about my account",
14     "preview": "A short preview of the email text...",
15     "text": "The full text body of the email.",
16     "html": "<html>...</html>",
17     "size": 2048,
18     "updated_at": "2023-10-27T10:00:00Z",
19     "created_at": "2023-10-27T10:00:00Z"
20   },
21   "thread": {
22     "inbox_id": "inbox_456def",
23     "thread_id": "thd_789ghi",
24     "labels": ["received"],
25     "timestamp": "2023-10-27T10:00:00Z",
26     "senders": ["Jane Doe <jane@example.com>"],
27     "recipients": ["Support Agent <support@agentmail.to>"],
28     "subject": "Question about my account",
29     "preview": "A short preview of the email text...",
30     "last_message_id": "<abc123@agentmail.to>",
31     "message_count": 1,
32     "size": 2048,
33     "updated_at": "2023-10-27T10:00:00Z",
34     "created_at": "2023-10-27T10:00:00Z"
35   }
36 }

`message.received.spam`

Description: Triggered when a new email is received and classified as spam. The payload structure is the same as message.received. Messages classified as spam are not delivered as message.received events.
Example use-case: Route spam to a review queue or log spam patterns for analysis.

This event is only delivered if the API key used to create the webhook has the label_spam_read permission. Without this permission, the webhook creation will be rejected with a 403 Forbidden error.

1 {
2   "type": "event",
3   "event_type": "message.received.spam",
4   "event_id": "evt_spam123",
5   "message": {
6     "inbox_id": "inbox_456def",
7     "thread_id": "thd_789ghi",
8     "message_id": "<spam123@example.com>",
9     "labels": ["spam"],
10     "timestamp": "2023-10-27T10:00:00Z",
11     "from": "spammer@example.com",
12     "to": ["agent@agentmail.to"],
13     "subject": "Suspicious offer",
14     "preview": "You've been selected...",
15     "text": "Full spam message body.",
16     "html": "<html>...</html>",
17     "size": 1024,
18     "updated_at": "2023-10-27T10:00:00Z",
19     "created_at": "2023-10-27T10:00:00Z"
20   },
21   "thread": {
22     "inbox_id": "inbox_456def",
23     "thread_id": "thd_789ghi",
24     "labels": ["spam"],
25     "timestamp": "2023-10-27T10:00:00Z",
26     "senders": ["spammer@example.com"],
27     "recipients": ["agent@agentmail.to"],
28     "subject": "Suspicious offer",
29     "preview": "You've been selected...",
30     "last_message_id": "<spam123@example.com>",
31     "message_count": 1,
32     "size": 1024,
33     "updated_at": "2023-10-27T10:00:00Z",
34     "created_at": "2023-10-27T10:00:00Z"
35   }
36 }

`message.received.blocked`

Description: Triggered when a new email is received and matched a block list entry. The payload structure is the same as message.received. Messages that match a block list are not delivered as message.received events.
Example use-case: Audit blocked senders or maintain a log of blocked messages.

This event is only delivered if the API key used to create the webhook has the label_blocked_read permission. Without this permission, the webhook creation will be rejected with a 403 Forbidden error.

1 {
2   "type": "event",
3   "event_type": "message.received.blocked",
4   "event_id": "evt_blocked456",
5   "message": {
6     "inbox_id": "inbox_456def",
7     "thread_id": "thd_789ghi",
8     "message_id": "<blocked456@example.com>",
9     "labels": ["blocked"],
10     "timestamp": "2023-10-27T10:00:00Z",
11     "from": "blocked-sender@example.com",
12     "to": ["agent@agentmail.to"],
13     "subject": "Blocked message",
14     "preview": "This message was blocked...",
15     "text": "Full blocked message body.",
16     "html": "<html>...</html>",
17     "size": 512,
18     "updated_at": "2023-10-27T10:00:00Z",
19     "created_at": "2023-10-27T10:00:00Z"
20   },
21   "thread": {
22     "inbox_id": "inbox_456def",
23     "thread_id": "thd_789ghi",
24     "labels": ["blocked"],
25     "timestamp": "2023-10-27T10:00:00Z",
26     "senders": ["blocked-sender@example.com"],
27     "recipients": ["agent@agentmail.to"],
28     "subject": "Blocked message",
29     "preview": "This message was blocked...",
30     "last_message_id": "<blocked456@example.com>",
31     "message_count": 1,
32     "size": 512,
33     "updated_at": "2023-10-27T10:00:00Z",
34     "created_at": "2023-10-27T10:00:00Z"
35   }
36 }

`message.received.unauthenticated`

Description: Triggered when a new email is received without authentication headers, so AgentMail cannot verify whether it is authenticated. These messages are processed and labeled unauthenticated because legitimate senders may omit the headers; messages with authentication headers that explicitly fail are dropped.
Example use-case: Monitor senders whose messages are missing authentication headers so you can decide whether to trust them or ask them to improve their email setup.

1 {
2   "type": "event",
3   "event_type": "message.received.unauthenticated",
4   "event_id": "evt_unauth789",
5   "message": {
6     "inbox_id": "inbox_456def",
7     "thread_id": "thd_789ghi",
8     "message_id": "<unauth789@example.com>",
9     "labels": ["unauthenticated"],
10     "timestamp": "2023-10-27T10:00:00Z",
11     "from": "sender@example.com",
12     "to": ["agent@agentmail.to"],
13     "subject": "Unauthenticated message",
14     "preview": "This message is missing authentication headers...",
15     "text": "Full unauthenticated message body.",
16     "html": "<html>...</html>",
17     "size": 512,
18     "updated_at": "2023-10-27T10:00:00Z",
19     "created_at": "2023-10-27T10:00:00Z"
20   },
21   "thread": {
22     "inbox_id": "inbox_456def",
23     "thread_id": "thd_789ghi",
24     "labels": ["unauthenticated"],
25     "timestamp": "2023-10-27T10:00:00Z",
26     "senders": ["sender@example.com"],
27     "recipients": ["agent@agentmail.to"],
28     "subject": "Unauthenticated message",
29     "preview": "This message is missing authentication headers...",
30     "last_message_id": "<unauth789@example.com>",
31     "message_count": 1,
32     "size": 512,
33     "updated_at": "2023-10-27T10:00:00Z",
34     "created_at": "2023-10-27T10:00:00Z"
35   }
36 }

`message.sent`

Description: Triggered when a message is successfully sent from one of your Inboxes.
Use Case: Track outgoing messages, update your database, or trigger follow-up workflows after sending.

1 {
2   "type": "event",
3   "event_type": "message.sent",
4   "event_id": "evt_456def",
5   "send": {
6     "inbox_id": "inbox_456def",
7     "thread_id": "thd_789ghi",
8     "message_id": "<abc123@agentmail.to>",
9     "timestamp": "2023-10-27T10:05:00Z",
10     "recipients": [
11       "recipient@example.com"
12     ]
13   }
14 }

`message.delivered`

Description: Triggered when a sent message is successfully delivered to the recipient’s mail server.
Use Case: Confirm successful delivery, update message status, or trigger delivery confirmation workflows.

1 {
2   "type": "event",
3   "event_type": "message.delivered",
4   "event_id": "evt_789ghi",
5   "delivery": {
6     "inbox_id": "inbox_456def",
7     "thread_id": "thd_789ghi",
8     "message_id": "<abc123@agentmail.to>",
9     "timestamp": "2023-10-27T10:06:00Z",
10     "recipients": [
11       "recipient@example.com"
12     ]
13   }
14 }

What is the difference between message.sent and message.delivered?

message.sent means the message has successfully left our servers and is out to travel the network. This typically happens before message.delivered where message.delivered means the receiving email server (whether it’s Gmail or Outlook) gives us the 200 OK saying the email has been received. What they do with the email after is unknown.

Does message.delivered mean I landed in their inbox?

Nope. As mentioned message.delivered means the receiving email server, whether it’s Gmail or Outlook tells us “Hey AgentMail, we got your email, we’ll take it from here!”. They typically have their own proprietary algorithms to determine whether the email is going to end up in the inbox or spam, but rest assured we handle everything needed for providers like Gmail to deem the emails primary inbox worthy

`message.bounced`

Description: Triggered when a sent message fails to deliver and bounces back. Includes bounce type and sub-type information.
Use Case: Handle bounced emails, update recipient status, or trigger bounce handling workflows.

1 {
2   "type": "event",
3   "event_type": "message.bounced",
4   "event_id": "evt_012jkl",
5   "bounce": {
6     "inbox_id": "inbox_456def",
7     "thread_id": "thd_789ghi",
8     "message_id": "<abc123@agentmail.to>",
9     "timestamp": "2023-10-27T10:07:00Z",
10     "type": "Permanent",
11     "sub_type": "General",
12     "recipients": [
13       {
14         "address": "invalid@example.com",
15         "status": "bounced"
16       }
17     ]
18   }
19 }

`message.complained`

Description: Triggered when a recipient marks your message as spam or files a complaint.
Use Case: Handle spam complaints, update sender reputation, or trigger complaint handling workflows.

1 {
2   "type": "event",
3   "event_type": "message.complained",
4   "event_id": "evt_345mno",
5   "complaint": {
6     "inbox_id": "inbox_456def",
7     "thread_id": "thd_789ghi",
8     "message_id": "<abc123@agentmail.to>",
9     "timestamp": "2023-10-27T10:08:00Z",
10     "type": "abuse",
11     "sub_type": "spam",
12     "recipients": [
13       "complainer@example.com"
14     ]
15   }
16 }

`message.rejected`

Description: Triggered when a message is rejected before being sent, typically due to validation errors or policy violations.
Use Case: Handle rejected messages, log rejection reasons, or trigger validation workflows.

1 {
2   "type": "event",
3   "event_type": "message.rejected",
4   "event_id": "evt_678pqr",
5   "reject": {
6     "inbox_id": "inbox_456def",
7     "thread_id": "thd_789ghi",
8     "message_id": "<abc123@agentmail.to>",
9     "timestamp": "2023-10-27T10:09:00Z",
10     "reason": "Invalid recipient address"
11   }
12 }

If you send an email to a bounced address, rejected address, or complained address we prevent you from sending to this email address ever again to keep bounce rates low. Make sure to keep your account bounce rate under 4%, otherwise we will put your account under review.

Domain Events

`domain.verified`

Description: Triggered when a domain is successfully verified and ready to use for sending emails.
Use Case: Automatically enable domain-specific features, update domain status, or trigger post-verification workflows.

1 {
2   "type": "event",
3   "event_type": "domain.verified",
4   "event_id": "evt_901stu",
5   "domain": {
6     "domain_id": "dom_123abc",
7     "status": "verified",
8     "feedback_enabled": true,
9     "records": [
10       // ... DNS verification records
11     ],
12     "created_at": "2023-10-27T09:00:00Z",
13     "updated_at": "2023-10-27T10:00:00Z"
14   }
15 }

Event Filtering

When creating a webhook, you can specify which events to subscribe to. This allows you to:

Reduce webhook traffic by only subscribing to events you need
Create specialized webhooks for specific workflows

For example, if you only need to trigger workflows on incoming messages, you can subscribe to just message.received. If you’re building a delivery tracking system, you might subscribe to message.sent, message.delivered, and message.bounced.

By default, spam, blocked, and unauthenticated events are not delivered. To receive them, you must explicitly include message.received.spam, message.received.blocked, or message.received.unauthenticated in the event_types list when creating your webhook. The API key must also have the corresponding label_spam_read or label_blocked_read permission for spam and blocked events.

If you have any specific webhook notifications you would like, please ping us in the #feature-requests channel in the Discord