REST API Reference
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 incoming webhook signatures using your Webhook secret token. This guarantees the request originated from MailSend and wasn't spoofed.
Supported Events
You can subscribe to these 7 real-time events:
| Event Name | Trigger Condition | Recommended Action |
|---|---|---|
| email.sent | The email dispatch was accepted by SES. | 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. |