Introduction to Webhooks

Mandrill'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 Mandrill account

To add a new webhook using the Manrill web application:

  1. Navigate to Settings in your Mandrill account.
  2. Click Webhooks from the top menu.
  3. Click + Add a Webhook at the top of the page.
  4. 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.).
  5. Add your webhook URL under Post To URL.
  6. Give your webhook an optional description under Description.
  7. Click Create Webhook.

Add a new webhook using the Mandrill API

Send a POST request the webhooks/add endpoint via the Mandrill API to create a new webhook. For example:

    "key": "example key",
    "url": "http://example/webhook-url",
    "description": "My Example Webhook",
    "events": [



Webhook and inbound route URLs should be set up to accept, at a minimum, POST requests. When you provide the URL where you want Mandrill 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, Mandrill 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 TypeDescription
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 Mandrill 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 Mandrill.

Event TypeDescription
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.