Complete reference for all AgentPost webhook event types and their payload structures

Webhook Events

AgentPost emits webhook events for key actions across your organization. Each event follows the common envelope format and contains event-specific data in the data field.

Event Types

Event Type	Trigger
`message.received`	An inbound email is received by an inbox
`message.sent`	An outbound email is accepted by the mail provider
`message.delivered`	An outbound email is confirmed delivered to the recipient
`message.bounced`	An outbound email bounces (hard or soft)
`message.complained`	A recipient marks an email as spam
`message.rejected`	An outbound email is rejected before sending
`domain.verified`	A custom domain passes DNS verification

message.received

Triggered when an inbound email arrives at one of your inboxes. This is the most commonly used event for AI agent workflows -- it signals that new work is available for processing.

Trigger: An email addressed to an inbox email address passes spam checks and is stored.

{
  "id": "evt_01JQ8X5K2M3N4P5R6S7T8V9W",
  "type": "message.received",
  "timestamp": "2026-03-08T14:30:00.000Z",
  "org_id": "org_01JQ8X5K2M3N4P5R6S7T8V9W",
  "env_id": "env_01JQ8X5K2M3N4P5R6S7T8V9W",
  "data": {
    "message_id": "msg_01JQ8X5K2M3N4P5R6S7T8V9W",
    "thread_id": "thr_01JQ8X5K2M3N4P5R6S7T8V9W",
    "inbox_id": "inb_01JQ8X5K2M3N4P5R6S7T8V9W",
    "from_address": "[email protected]",
    "to_addresses": ["[email protected]"],
    "subject": "Need help with billing integration",
    "extracted_text": "Hi, I'm having trouble setting up the billing webhook. Can you help?",
    "has_attachments": false,
    "received_at": "2026-03-08T14:30:00.000Z"
  }
}

Field	Type	Description
`message_id`	string	Unique message identifier
`thread_id`	string	Thread this message belongs to
`inbox_id`	string	Inbox that received the message
`from_address`	string	Sender's email address
`to_addresses`	string[]	Recipient email addresses
`subject`	string	Email subject line
`extracted_text`	string	Clean reply text with quotes stripped
`has_attachments`	boolean	Whether the message has file attachments
`received_at`	string	ISO 8601 timestamp of receipt

Triggered when an outbound email is successfully accepted by the mail provider (AWS SES). This confirms the email entered the delivery pipeline -- it does not mean the email has reached the recipient's inbox yet.

Trigger: AWS SES accepts the email for delivery.

{
  "id": "evt_01JQ9A2B3C4D5E6F7G8H9J0K",
  "type": "message.sent",
  "timestamp": "2026-03-08T14:31:00.000Z",
  "org_id": "org_01JQ8X5K2M3N4P5R6S7T8V9W",
  "env_id": "env_01JQ8X5K2M3N4P5R6S7T8V9W",
  "data": {
    "message_id": "msg_01JQ9A2B3C4D5E6F7G8H9J0K",
    "thread_id": "thr_01JQ8X5K2M3N4P5R6S7T8V9W",
    "inbox_id": "inb_01JQ8X5K2M3N4P5R6S7T8V9W",
    "from_address": "[email protected]",
    "to_addresses": ["[email protected]"],
    "subject": "Re: Need help with billing integration",
    "ses_message_id": "01000192-1234-5678-9abc-def012345678",
    "sent_at": "2026-03-08T14:31:00.000Z"
  }
}

Field	Type	Description
`message_id`	string	Unique message identifier
`thread_id`	string	Thread this message belongs to
`inbox_id`	string	Inbox the message was sent from
`from_address`	string	Sender address
`to_addresses`	string[]	Recipient addresses
`subject`	string	Email subject line
`ses_message_id`	string	AWS SES message identifier for tracking
`sent_at`	string	ISO 8601 timestamp of send

message.delivered

Triggered when an outbound email is confirmed delivered to the recipient's mail server. This is the strongest positive signal -- it means the email arrived.

Trigger: AWS SES receives a delivery notification from the recipient's mail server.

{
  "id": "evt_01JQ9B3C4D5E6F7G8H9J0K1L",
  "type": "message.delivered",
  "timestamp": "2026-03-08T14:32:00.000Z",
  "org_id": "org_01JQ8X5K2M3N4P5R6S7T8V9W",
  "env_id": "env_01JQ8X5K2M3N4P5R6S7T8V9W",
  "data": {
    "message_id": "msg_01JQ9A2B3C4D5E6F7G8H9J0K",
    "thread_id": "thr_01JQ8X5K2M3N4P5R6S7T8V9W",
    "inbox_id": "inb_01JQ8X5K2M3N4P5R6S7T8V9W",
    "to_addresses": ["[email protected]"],
    "delivered_at": "2026-03-08T14:32:00.000Z",
    "processing_time_ms": 1250
  }
}

Field	Type	Description
`message_id`	string	Original message identifier
`thread_id`	string	Thread identifier
`inbox_id`	string	Inbox the message was sent from
`to_addresses`	string[]	Recipients that received the email
`delivered_at`	string	ISO 8601 timestamp of confirmed delivery
`processing_time_ms`	number	Time from send to delivery confirmation in ms

message.bounced

Triggered when an outbound email bounces. Bounces can be hard (permanent failure) or soft (temporary issue). Monitoring bounces is critical for maintaining your sending reputation.

Trigger: AWS SES receives a bounce notification from the recipient's mail server.

{
  "id": "evt_01JQ9C4D5E6F7G8H9J0K1L2M",
  "type": "message.bounced",
  "timestamp": "2026-03-08T14:33:00.000Z",
  "org_id": "org_01JQ8X5K2M3N4P5R6S7T8V9W",
  "env_id": "env_01JQ8X5K2M3N4P5R6S7T8V9W",
  "data": {
    "message_id": "msg_01JQ9A2B3C4D5E6F7G8H9J0K",
    "thread_id": "thr_01JQ8X5K2M3N4P5R6S7T8V9W",
    "inbox_id": "inb_01JQ8X5K2M3N4P5R6S7T8V9W",
    "bounce_type": "Permanent",
    "bounce_sub_type": "General",
    "bounced_recipients": [
      {
        "email_address": "[email protected]",
        "status": "5.1.1",
        "diagnostic_code": "smtp; 550 5.1.1 The email account does not exist"
      }
    ],
    "bounced_at": "2026-03-08T14:33:00.000Z"
  }
}

Field	Type	Description
`message_id`	string	Original message identifier
`thread_id`	string	Thread identifier
`inbox_id`	string	Inbox the message was sent from
`bounce_type`	string	`Permanent` (hard) or `Transient` (soft)
`bounce_sub_type`	string	Sub-category: `General`, `NoEmail`, `Suppressed`
`bounced_recipients`	array	List of recipients that bounced
`bounced_at`	string	ISO 8601 timestamp of bounce

Bounce Types:

Permanent (hard bounce): The address does not exist or is permanently unreachable. Remove it from your lists immediately.
Transient (soft bounce): Temporary issue (mailbox full, server unavailable). Can retry later, but repeated soft bounces may indicate a problem.

message.complained

Triggered when a recipient marks one of your emails as spam. Complaint rates above 0.1% can severely impact your sending reputation. Monitor this event closely.

Trigger: AWS SES receives a complaint feedback report from the recipient's email provider.

{
  "id": "evt_01JQ9D5E6F7G8H9J0K1L2M3N",
  "type": "message.complained",
  "timestamp": "2026-03-08T14:34:00.000Z",
  "org_id": "org_01JQ8X5K2M3N4P5R6S7T8V9W",
  "env_id": "env_01JQ8X5K2M3N4P5R6S7T8V9W",
  "data": {
    "message_id": "msg_01JQ9A2B3C4D5E6F7G8H9J0K",
    "inbox_id": "inb_01JQ8X5K2M3N4P5R6S7T8V9W",
    "complained_recipients": ["[email protected]"],
    "feedback_type": "abuse",
    "complained_at": "2026-03-08T14:34:00.000Z"
  }
}

Field	Type	Description
`message_id`	string	Original message identifier
`inbox_id`	string	Inbox the message was sent from
`complained_recipients`	string[]	Recipients who filed the complaint
`feedback_type`	string	Complaint type (typically `abuse`)
`complained_at`	string	ISO 8601 timestamp of complaint

message.rejected

Triggered when an outbound email is rejected before it enters the delivery pipeline. This typically happens due to policy violations, block list matches, or rate limiting.

Trigger: AgentPost or AWS SES rejects the email before attempting delivery.

{
  "id": "evt_01JQ9E6F7G8H9J0K1L2M3N4P",
  "type": "message.rejected",
  "timestamp": "2026-03-08T14:35:00.000Z",
  "org_id": "org_01JQ8X5K2M3N4P5R6S7T8V9W",
  "env_id": "env_01JQ8X5K2M3N4P5R6S7T8V9W",
  "data": {
    "inbox_id": "inb_01JQ8X5K2M3N4P5R6S7T8V9W",
    "from_address": "[email protected]",
    "to_addresses": ["[email protected]"],
    "subject": "Your order has shipped",
    "rejection_reason": "blocked_recipient",
    "rejection_detail": "Recipient blocked by organization filter rules",
    "rejected_at": "2026-03-08T14:35:00.000Z"
  }
}

Field	Type	Description
`inbox_id`	string	Inbox that attempted to send
`from_address`	string	Sender address
`to_addresses`	string[]	Intended recipients
`subject`	string	Email subject line
`rejection_reason`	string	Reason code: `blocked_recipient`, `rate_limited`, `account_paused`
`rejection_detail`	string	Human-readable rejection explanation
`rejected_at`	string	ISO 8601 timestamp of rejection

domain.verified

Triggered when a custom domain passes DNS verification (SPF, DKIM, and optionally DMARC). This signals that the domain is ready for sending and receiving email.

Trigger: AgentPost's domain verification job confirms all required DNS records are in place.

{
  "id": "evt_01JQ9F7G8H9J0K1L2M3N4P5R",
  "type": "domain.verified",
  "timestamp": "2026-03-08T14:36:00.000Z",
  "org_id": "org_01JQ8X5K2M3N4P5R6S7T8V9W",
  "env_id": "env_01JQ8X5K2M3N4P5R6S7T8V9W",
  "data": {
    "domain_id": "dom_01JQ9F7G8H9J0K1L2M3N4P5R",
    "domain_name": "mail.acmeco.com",
    "verification_status": "verified",
    "spf_status": "verified",
    "dkim_status": "verified",
    "dmarc_status": "verified",
    "verified_at": "2026-03-08T14:36:00.000Z"
  }
}

Field	Type	Description
`domain_id`	string	Domain identifier
`domain_name`	string	The verified domain name
`verification_status`	string	Overall status: `verified`
`spf_status`	string	SPF record verification status
`dkim_status`	string	DKIM record verification status
`dmarc_status`	string	DMARC record verification status
`verified_at`	string	ISO 8601 timestamp of verification

Subscribing to Events

When creating or updating a webhook endpoint, specify the event types you want to receive:

import AgentPost from '@agentpost/sdk';

const client = new AgentPost({ apiKey: 'ap_sk_live_your_key_here' });

// Subscribe to specific events
const endpoint = await client.webhookEndpoints.create({
  url: 'https://your-app.com/webhooks/agentpost',
  events: [
    'message.received',
    'message.bounced',
    'message.complained',
    'domain.verified',
  ],
});

from agentpost import AgentPost

client = AgentPost(api_key="ap_sk_live_your_key_here")

# Subscribe to specific events
endpoint = client.webhook_endpoints.create(
    url="https://your-app.com/webhooks/agentpost",
    events=[
        "message.received",
        "message.bounced",
        "message.complained",
        "domain.verified",
    ],
)

curl -X POST https://api.agent-post.dev/api/v1/webhooks/endpoints \
  -H "Authorization: Bearer ap_sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/agentpost",
    "events": [
      "message.received",
      "message.bounced",
      "message.complained",
      "domain.verified"
    ]
  }'

Next Steps

Setup Guide -- Build a webhook receiver step by step
Verifying Webhooks -- Validate webhook signatures for security

Webhook Events

On this page