Webhooks

• message.received — A new inbound email arrived
• message.sent — An outbound email was accepted for delivery
• message.delivered — An outbound email was delivered to the recipient
• message.bounced — An outbound email permanently bounced
• message.complaint — A recipient marked the email as spam

Webhook payloads are POST requests to your endpoint URL (must be HTTPS). Each delivery includes a JSON body with the event type, timestamp, and relevant data.

If your endpoint returns a non-2xx status, Robotomail retries with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours. After 10 consecutive failures, the webhook is automatically paused with status FAILED.

Every webhook delivery includes an X-Robotomail-Signature header containing an HMAC-SHA256 signature of the request body. Verify it against the webhook secret returned when you created the webhook.

See the Webhooks API reference or the Receive & reply guide for verification examples. The secret is only returned once at creation time.

You can attach custom HTTP headers to a webhook that are included in every delivery request. This is useful for passing authentication tokens, routing keys, or other metadata your endpoint requires.

Pass a headers object when creating or updating a webhook. Up to 10 headers are allowed (key max 256 chars, value max 1024 chars). Header names must be valid HTTP tokens — spaces, colons, and other non-token characters are rejected. Values must not contain control characters (prevents CRLF injection). Headers with the X-Robotomail- prefix are reserved and will be rejected. Dangerous headers (Host, Content-Length, Content-Type, Transfer-Encoding, Connection, Keep-Alive, Upgrade, TE, Trailer) are also blocked. To clear all custom headers, pass null in a PATCH request.

Webhooks can be account-level (triggered for events on any mailbox) or mailbox-scoped (triggered only for events on a specific mailbox). Scoped API keys can only create mailbox-scoped webhooks for mailboxes in their scope.