Event reference
Every AI Inbx webhook event type, the envelope they share, what each one means, and how to handle email, thread, domain and mailbox events.
Every webhook event arrives in the same envelope:
{
"id": "evt_...",
"type": "email.received",
"created_at": "2026-09-01T10:31:04Z",
"space_id": null,
"data": { }
}id is stable across retries and replays — deduplicate on it. space_id is the space the resource is in, null for the workspace itself. data varies by type, and both SDKs discriminate on type so a type checker narrows it for you.
| Event | Fires when |
|---|---|
email.received |
Inbound mail arrives. |
email.sent |
A message is handed to the mail provider. |
email.delivered |
The receiving server accepted it. |
email.bounced |
Delivery failed. |
email.complained |
The recipient marked it as spam. |
email.failed |
The provider refused it before any attempt. |
email.unsubscribed |
The recipient opted out. |
email.opened |
An open was tracked. |
email.clicked |
A tracked link was clicked. |
Thread
| Event | Fires when |
|---|---|
thread.created |
A new conversation started. |
Domain
| Event | Fires when |
|---|---|
domain.verified |
The domain’s DKIM identity was verified. |
domain.lost |
A verified domain’s DKIM record stopped resolving. |
Mailbox
| Event | Fires when |
|---|---|
mailbox.connected |
A customer authorized a mailbox. |
mailbox.needs_reauth |
A mailbox’s authorization stopped working. |
mailbox.disconnected |
A mailbox was removed. |
Handle events in a worker
Verify and durably enqueue each event in your HTTP handler. In a worker, branch on event.type to select the appropriate application behavior:
| Type | Typical action |
|---|---|
email.received |
Load the message or thread and evaluate whether to respond |
email.bounced |
Record affected recipients and whether the failure is permanent |
email.failed |
Surface the provider’s reason; the message never went out |
email.complained |
Record the complaint and review the recipient’s suppression state |
email.unsubscribed |
Update the matching preference in your application |
mailbox.needs_reauth |
Ask the mailbox owner to reconnect |
Make each action recoverable and idempotent. Mark work complete after it succeeds. Unknown event types should not crash the handler; record the type for diagnosis and ignore it until the application supports it.
Verifying requests
How to authenticate each delivery before storing or processing it.