Skip to main content
Webhooks POST events to your HTTPS endpoint when mail is delivered, rejected, bounced, complained about, or received by a mailbox.
Each team starts with 10 webhooks. See Team limits.

​
Webhooks or realtime events

Use webhooks when your backend should receive signed event POSTs, even while your app is offline. Use the Mailbox API event stream when a mailbox client can keep a live Server-Sent Events connection open and needs immediate received-message updates.

​
Create a webhook

1

Open Webhooks

Open Webhooks in the team workspace and select Create webhook.
2

Enter the endpoint

Add a name, an HTTPS URL, and the event types you want to receive.
3

Choose filters

Keep the webhook team-wide, or scope it to selected mailboxes.
4

Store the secret

Copy the signing secret when it appears. It is shown once.

​
Process events

Every delivery includes a JSON body and headers that identify the event.
HeaderUse
X-Sendmux-SignatureVerify the payload with the webhook secret.
X-Sendmux-Event-IdDedupe retries for the same event.
X-Sendmux-Event-TypeRoute the event in your application.
X-Sendmux-Delivery-AttemptTrack retry attempts.
Verify the signature before acting on an event. See Verify webhook signatures.

​
Event types

Event typeWhen it fires
message.deliveredA recipient system accepted the message.
message.bouncedA message bounced.
message.complainedA recipient marked a message as spam.
message.rejectedThe sending system rejected the message before delivery.
message.delivery_delayedDelivery is delayed and still being retried.
message.receivedA mailbox received an inbound message.
message.received.spamA mailbox received an inbound message classified as spam.
sendmux.testA synthetic event for testing a webhook.

​
Retries

Your endpoint should return 2xx quickly. Non-2xx responses and timeouts are retried across a 24-hour window. After the final failed attempt, Sendmux marks the webhook as failing and emails the team owner. Fix the endpoint, then disable and re-enable the webhook to resume delivery.

​
Review deliveries

Open a webhook to review recent attempts, response status, latency, retry state, and retained payload availability. Delivery metadata and retained payloads are kept for 7 days. Use Rotate secret if a signing secret may have leaked. The new secret is shown once and is used for future deliveries. Use Send test to publish a sendmux.test event. Add sendmux.test to the webhook event list before testing.

​
API access

Use the Management API when you need to create webhooks, list attempts, fetch retained payloads, rotate secrets, or send test events from your own tooling.

Management API

Open the generated Webhooks endpoint reference.

Verify signatures

Check webhook payloads before processing events.

Webhook replay

See the coming-soon replay action.

Mailboxes

Receive inbound mailbox events.

Mailbox API events

Stream live mailbox events with a mailbox key.

Delivery logs

Compare webhook events with delivery logs.