Webhooks

Webhooks allow you to subscribe to real-time notifications about various events that occur in MailerSend.

You can create a webhook directly from your MailerSend account and listen for events so your integration can automatically trigger reactions.

Webhooks overview

Setup

Currently, you can create a webhook using the API endpoints listed below or directly from your account. Read more about webhooks.

Available events

These are all the events you can listen to and send a notification for.

Event	Description
activity.sent	Fired when your email is sent from our sending servers. We are now waiting for a response from the receiving servers.
activity.delivered	Fired when your email is successfully delivered with no errors.
activity.soft_bounced	Fired when your email is not delivered because it soft bounced.
activity.hard_bounced	Fired when your email is not delivered.
activity.opened	Fired when the recipient receives your email and opens it.
activity.clicked	Fired when the recipient clicks a link in your email.
activity.unsubscribed	Fired when the recipient unsubscribes from your emails.
activity.spam_complaint	Fired when the recipient marks your emails as spam or junk.

Payload example

Our responses contain fat payloads, including the information about the event-related object, so there is no need to make an additional API request.

An example of activity.sent event:

{
  "type": "activity.sent",
  "domain_id": "yv69oxl5kl785kw2",
  "created_at": "2020-11-27T10:08:08.298647Z",
  "webhook_id": "2351ndgwr4zqx8ko",
  "url": "https://your-domain.com/webhook",
  "data": {
    "object": "activity",
    "id": "5fc0d006b42c3e16e1774882",
    "type": "sent",
    "created_at": "2020-11-27T10:08:06.258000Z",
    "email": {
      "object": "email",
      "id": "5fc0d003e7a5e7035446aa32",
      "created_at": "2020-11-27T10:08:03.923000Z",
      "from": "test@mailersend.com",
      "subject": "Test email",
      "status": "sent",
      "tags": null,
      "message": {
        "object": "message",
        "id": "5fc0d003f718c90162341852",
        "created_at": "2020-11-27T10:08:03.017000Z"
      },
      "recipient": {
        "object": "recipient",
        "id": "5f6887d6fd913a6523283fd2",
        "email": "test@mailersend.com",
        "created_at": "2020-09-21T11:00:38.184000Z"
      }
    },
    "template_id": "7nxe3yjmeq28vp0k",
    "morph": null
  }
}

Security

Webhook requests made by MailerSend include a Signature header. It contains a string generated by hashing the data sent to your webhook endpoint with an individual Signing Secret. A signing secret is a random string that is generated when you create a webhook.

Verifying a signature:

// $signature - a header sent by MailerSend, please refer to your framework
// or PHP manual on how to read the Signature header

// $requestContent - please refer to your framework or PHP manual on how to read the request content

$computedSignature = hash_hmac('sha256', $requestContent, $signingSecret);
return hash_equals($signature, $computedSignature);

Retrying failed webhooks

When your webhook receives a response other than a 2xx code from your endpoint URL, or if the endpoint doesn’t respond within 3 seconds, it will show up as a failed attempt in the log section of your webhook. If it receives a 2xx, then it will show as a success.

If a webhook call fails, MailerSend will retry the call a couple of times, waiting 10 seconds between the first and second attempt and 100 seconds between the second and the third attempt. This is to avoid hammering the application you want to send the information to.

Useful tools

Webhook.site or Pipedream.com are useful tools for testing webhooks quickly, seeing how it works, and inspecting what's being sent—without any coding on your side.

FAQs

• How do I track the Message I've sent via SMTP relay back to a webhook?

If the message was sent successfully, our SMTP relay will send you back a 250 Message queued as XXXXXX response. This can be parsed to an ID used in our Messages endpoints, and in webhooks that Message ID can be found at data.email.message.id.

If you want full interoperability, we encourage you to use our Email API for the best results.

List webhooks

If you want to retrieve information about webhooks, use this GET request:

GET https://api.mailersend.com/v1/webhooks

Request parameters

Parameter	Type	Required	Limitations	Details
domain_id	string	yes

Get a webhook

To retrieve information about a single webhook, use this GET request:

GET https://api.mailersend.com/v1/webhooks/{webhook_id}

Create a webhook

Create a webhook using this POST request:

POST https://api.mailersend.com/v1/webhooks/

Request parameters

Parameter	Type	Required	Limitations	Details
url	url	yes
name	string	yes	Max: 191
events	array	yes
enabled	boolean	optional
domain_id	string	yes		Existing hashed domain ID.

Update a webhook

Update a webhook using this PUT request:

PUT https://api.mailersend.com/v1/webhooks/{webhook_id}

Parameter	Type	Required	Limitations	Details
url	url	optional
name	string	optional	Max: 191
events	array	optional
enabled	boolean	optional

Delete a webhook

Delete a webhook using this DELETE request:

DELETE https://api.mailersend.com/v1/webhooks/{webhook_id}