Transactional Email's webhooks allow your application to receive information about email events as they occur. You can configure and test webhooks using the Webhooks settings page in your account, or via the API.
Configure Webhook URLs
Add a new webhook in your Transactional Email account
To add a new webhook using the Transactional Email web application:
- Navigate to Settings in your Transactional Email account.
- Click Webhooks from the top menu.
- Click + Add a Webhook at the top of the page.
- Choose the events you want to listen for (for example, when an email is sent, bounces, is opened, is marked as spam, is clicked, etc.).
- Add your webhook URL under Post To URL.
- Give your webhook an optional description under Description.
- Click Create Webhook.
Add a new webhook using the Transactional API
Send a POST request the webhooks/add endpoint via the Transactional API to create a new webhook. For example:
{
"key": "example key",
"url": "http://example/webhook-url",
"description": "My Example Webhook",
"events": [
"send",
"open",
"click",
"hard_bounce",
"spam"
]
}
Note
Webhook and inbound route URLs should be set up to accept, at a minimum, POST requests. When you provide the URL where you want Transactional Email to POST the data for events, we'll do a quick check that the URL exists by using a HEAD request (not POST).
If the URL doesn't exist or returns something other than a 200 HTTP response to the HEAD request, Transactional Email will fallback and attempt a POST request. In this case, the POST request, the mandrill_events parameter will be an empty array, and the POST will be signed with a generic key (with the value 'test-webhook').
Event Types
Message event webhooks
Webhooks can be triggered when an email is sent, opened, clicked, etc. Message event webhooks have several types of events:
| Event Type | Description |
|---|---|
| Sent | message has been sent successfully |
| Bounced | message has hard bounced |
| Opened | recipient opened a message; will only occur when open tracking is enabled |
| Marked As Spam | recipient marked a message as spam |
| Rejected | message was rejected |
| Delayed | message has been sent, but the receiving server has indicated mail is being delivered too quickly and Transactional Email should slow down sending temporarily |
| Soft-Bounced | message has soft bounced |
| Clicked | recipient clicked a link in a message; will only occur when click tracking is enabled |
| Recipient Unsubscribes | recipient unsubscribed |
Sync event webhooks
Sync webhooks are designed to alow you to sync data to an external data source. They aren't message-based but rather help you track changes to data stored in Transactional Email.
| Event Type | Description |
|---|---|
| Rejection Blacklist Changes | triggered when a Rejection Blacklist entry is added, changed, or removed |
| Rejection Whitelist Changes | triggered when a Rejection Whitelist entry is added or removed |
View a detailed description of the data format for webhooks.