Webhooks

A message-received event delivered to your endpoint

The payload delivered to a registered webhook endpoint the moment a message is received in one of your inboxes — and the same envelope the **WebSocket** stream relays for a live connection. The delivery is signed; verify the signature before trusting the body. `event_type` carries the dotted spelling over webhooks/REST (the WebSocket stream uses the underscore spelling); the two classified variants (`message.received.spam`, `message.received.unauthenticated`) are only delivered to endpoints/keys permitted to read classified mail.

The payload delivered to a registered webhook endpoint the moment a message is received in one of your inboxes — and the same envelope the WebSocket stream relays for a live connection. The delivery is signed; verify the signature before trusting the body. event_type carries the dotted spelling over webhooks/REST (the WebSocket stream uses the underscore spelling); the two classified variants (message.received.spam, message.received.unauthenticated) are only delivered to endpoints/keys permitted to read classified mail.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The self-describing event envelope delivered over webhooks and the WebSocket stream. Named top-level keys — no generic data wrapper — and no top-level timestamp (the delivery time is the signature's timestamp). The embedded message and thread are the full resources in the exact shape the REST API returns (message_id/thread_id typed ids, inbox_id = the inbox's email), so a consumer acts on the delivered payload without a follow-up read.

Response Body

Example Requests

The self-describing event envelope delivered over webhooks and the WebSocket stream. Named top-level keys — no generic data wrapper — and no top-level timestamp (the delivery time is the signature's timestamp). The embedded message and thread are the full resources in the exact shape the REST API returns (message_id/thread_id typed ids, inbox_id = the inbox's email), so a consumer acts on the delivered payload without a follow-up read.

POST/message.received

List webhooks GET

List the tenant's webhooks, newest-first by default, with cursor pagination. The signing secret is never included in a listing — it is shown only once at creation.

Update a webhook PATCH

Partially update a webhook's `url`, `event_types`, `inbox_ids`, and/or `enabled` flag. At least one field must be supplied. `event_types` is **replace-not-merge** — the supplied array becomes the whole filter set. Set `enabled: false` to pause deliveries without deleting the endpoint.