Webhooks
Receive real-time notifications about delivery statuses, complaints, opens, and link clicks.
Docs Summary
- What this page explains: Listening to real-time events like deliveries, opens, bounces, and complaints.
- Who should use it: Developers syncing contact records and updating analytics dashboards.
- Related MailSend feature: Event subscription, delivery logs
- Common use cases: Automated sync, bounce monitoring, suppression rules
- Related docs: Email API, SDK Reference, Campaigns
Webhooks let you monitor and handle events asynchronously on your servers. When an event fires, MailSend sends a JSON POST request containing event payload metadata to your configured callback endpoint.
Always verify the X-MailSend-Signature header against the exact raw request body using HMAC-SHA256 before parsing JSON. Reject timestamps more than five minutes from your server clock and compare signatures in constant time.
Replay protection and secret rotation
Use X-MailSend-Delivery-Id as an idempotency key and persist accepted IDs so automatic retries cannot be processed twice. X-MailSend-Secret-Version identifies the signing key. When you rotate a secret, MailSend shows the new value once and keeps the previous version available for in-flight retries for 24 hours; receivers should temporarily accept both versions, then remove the old one. Rotation is admin-only.
Webhook endpoints must use HTTPS. MailSend blocks loopback, private, link-local, metadata-service, credential-bearing, and DNS-rebinding destinations; redirects are not followed. Failed deliveries use bounded exponential retry and become failed/dead-letter items after eight attempts, where an admin can explicitly replay them.
Supported Events
You can subscribe to these 7 real-time events:
| Event Name | Trigger Condition | Recommended Action |
|---|---|---|
| email.sent | The email dispatch was submitted for delivery. | Log queue attempt. |
| email.delivered | The ISP confirmed receipt of the email. | Update database status to Delivered. |
| email.bounced | The recipient server rejected the email (hard/soft bounce). | Add to suppression list to protect domain key score. |
| email.complained | The recipient marked your email as spam. | Immediately suppress and stop further marketing campaigns. |
| email.opened | The user opened the email tracking pixel. | Trigger next automation step or update analytics dashboard. |
| email.clicked | The recipient clicked a tracked link. | Track conversion and user engagement. |
| email.unsubscribed | The recipient clicked the 1-click unsubscribe link. | Remove contact from active mailing lists. |