Email Webhooks for Reliable Inbound Mail

Email webhooks push email events to your HTTPS endpoint, removing the delay and repeated requests of polling. The reliable pattern is simple: verify, accept durably, acknowledge, then process in a worker.

That pattern suits support queues, document ingestion, and AI agent inboxes. It also gives you a clear recovery boundary when a handler or downstream service fails.

What is an email webhook?

An email webhook is an HTTP callback for an email event. The provider sends a signed POST when something changes, and your endpoint returns a successful response after it has safely accepted the event.

Webhooks are push delivery. Polling is pull delivery: your application asks for changes on a schedule and accepts the delay between checks. Neither is universally better; the right choice depends on latency, durability, and network constraints.

How does an inbound email webhook flow work?

The receiving service accepts and parses the message before creating a provider-neutral event. The event carries identifiers and routing metadata; your worker fetches full message content or attachment metadata only when the workflow needs it.

1. Accept an inbound message.

2. Create and route message.received.

3. Sign the exact JSON body.

4. Verify the unchanged request bytes.

5. Record the event ID atomically.

6. Return 2xx after durable acceptance.

7. Process message details in a worker.

The durable step matters. Returning success after a queue write fails tells the sender to stop retrying even though your system lost the event. If acceptance fails, return a failure and let the delivery policy retry.

Which email webhook events and fields matter?

Event names are provider contracts, not a universal vocabulary. Build against the exact schema you receive and keep the provider event ID separate from an email's RFC 5322 Message-ID.

Sendmux currently exposes these webhook event types:

A Sendmux webhook event includes a stable event ID, event type, team ID, occurrence time, and typed data. Event data can include message IDs, sender, recipients, mailbox ID, and delivery classifications.

Route each event by its Sendmux event type. Deduplicate with the Sendmux event ID, and keep the delivery-attempt number for diagnostics rather than business decisions.

How should an email webhook handler be structured?

Keep the handler boundary narrow: authenticate the raw bytes, validate the event envelope, accept the work once, and respond. Parse documents, call models, and update CRM records in the worker.

Use this order:

1. Read the raw request bytes.

2. Verify HMAC-SHA256 in constant time.

3. Validate the event envelope.

4. Accept the event ID and job atomically.

5. Return 2xx for an accepted event.

6. Fail when durable acceptance fails.

7. Run slow work in a retry-safe worker.

Do not deduplicate only on message_id. One message can produce different events, while a retry of the same event keeps its event ID. The idempotency record should therefore bind the provider event ID to the work it authorises.

How do Sendmux webhook signatures and retries work?

Sendmux signs the exact webhook request body with HMAC-SHA256 and returns a hexadecimal signature. The signing secret is shown only at webhook creation or secret rotation.

Verify the signature before parsing or processing the payload. Any middleware that reformats JSON can change the signed bytes, so preserve the raw body and use a constant-time comparison for the final digest check.

Sendmux retries timeouts and non-successful responses across a bounded window, with up to eight delivery attempts. A 410 Gone response is treated as a permanent instruction to stop delivering to that endpoint.

The delivery view retains recent attempt metadata, including response status, latency, retry state, and payload availability. That makes the event ID your join key across application logs and Sendmux delivery diagnostics.

How should attachments be processed?

Keep attachment bytes out of the webhook transaction. The Sendmux webhook payload identifies the event and mailbox context; it does not embed presigned attachment download URLs.

After durable acceptance, use the Mailbox API to fetch message or attachment metadata. Each attachment read returns one short-lived download link; use it promptly and refresh metadata after expiry.

This helps keep reusable attachment links from being stored in retained webhook payloads. A retry-safe worker can safely retry to fetch the full body, one attachment, or metadata as needed.

When should you use SSE instead of webhooks?

Use the Mailbox API's Server-Sent Events stream when a connected client needs bounded real-time mailbox updates but cannot host a public callback. Sendmux streams message.received and message.received.spam events with message context and supports resumption.

SSE is a live connection, not a durable background worker. A server integration should still use webhooks when it needs provider-driven delivery while the application is otherwise idle.

Microsoft Graph uses a different subscription model for Outlook messages. It validates the public notification URL, sends change notifications while the subscription remains valid, and requires renewal before expiry.

How do you set up email webhooks safely?

Start with one event and one disposable mailbox, then prove the whole path before widening the subscription.

1. Register a public HTTPS endpoint.

2. Store the signing secret securely.

3. Verify raw-body signatures and schema.

4. Deduplicate event IDs during acceptance.

5. Send and correlate a test event.

6. Test failures, duplicates, and retries.

7. Add only required mailbox filters.

Avoid storing raw webhook payloads by default. Retain the minimum fields needed for idempotency, routing, diagnosis, and your stated retention policy, and keep secrets and sensitive message content out of ordinary logs.

Why Sendmux fits webhook-driven inbox workflows

Sendmux combines outbound sending and inbound mailboxes for AI agents and SaaS platforms. Its webhooks use provider-neutral event names, mailbox filters, signed payloads, bounded retries, and delivery diagnostics.

For connected tools, the Mailbox API also exposes an SSE stream. For background systems, signed webhooks provide the durable push boundary, while the Mailbox API supplies full message and attachment data on demand.

That separation keeps the callback small: accept the event first, then let a worker retrieve and process the email content it actually needs.

Email webhook production checklist

1. Verify signatures against the exact raw body.

2. Deduplicate each provider event ID.

3. Return success only after durable acceptance.

4. Process slow work asynchronously.

5. Subscribe only to events you use.

6. Fetch messages after durable acceptance.

7. Test failures, duplicates, and replays.

8. Monitor delivery and worker failures.

Sources

• Sendmux webhook setup

• Verify Sendmux webhook signatures

• Sendmux webhook replay and delivery attempts

• Microsoft Graph webhook delivery

• Stripe webhook best practices

• RFC 2104: HMAC