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 webhooksopen in new window.

Webhook Failure Warning

If your webhook fails 10 times within 24 hours, you will receive a notification. If the failures reach 20 within the same period, the webhook will be paused automatically, and no further notifications will be sent until the webhook is re-enabled.

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.opened_unique`	Fired when the recipient receives your email and opens it only for the first time.
`activity.clicked`	Fired when the recipient clicks a link in your email.
`activity.clicked_unique`	Fired when the recipient clicks a link in your email only for the first time.
`activity.unsubscribed`	Fired when the recipient unsubscribes from your emails.
`activity.spam_complaint`	Fired when the recipient marks your emails as spam or junk.
`activity.survey_opened`	Fired when the recipient opens an email containting a survey for the first time.
`activity.survey_submitted`	Fired when the recipient answers all available questions in a survey based email or after an idle time of `30` minutes.
`sender_identity.verified`	Fired when the sender identity has been successfully verified.
`maintenance.start`	Fired when the maintenance period begins. (More info in Handling Maintenance Modes).
`maintenance.end`	Fired when the maintenance period ends. (More info in Handling Maintenance Modes).
`inbound_forward.failed`	Fired when an inbound message fail to forward.
`email_single.verified`	Fired when single email has been successfully verified.
`email_list.verified`	Fired when email verification list has been successfully verified.
`bulk_email.completed`	Fired when bulk email sending has been successfully completed.

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
  }
}

An example of activity.survey_submitted 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": {
    "email": {
      "object": "email",
      "id": "643e785e1ad4b461a307e5d2",
      "created_at": "2023-04-18T11:00:46.609000Z",
      "from": "test@domain.com",
      "subject": "Test email",
      "status": "sent",
      "tags": null,
      "preview_url": "http://preview.mailersend.com/email/643e785e1ad4b461a307e5d2",
      "template": {
        "object": "template",
        "id": "83gwk2j7zqz1nxyd",
        "url": "http://app.mailersend.com/templates/83gwk2j7zqz1nxyd"
      },
      "message": {
        "object": "message",
        "id": "643e785d4d8189e0ef046aa2",
        "created_at": "2023-04-18T11:00:45.398000Z"
      },
      "recipient": {
        "object": "recipient",
        "id": "6410951922b6316e210cb2e2",
        "email": "reciepient@email.com",
        "created_at": "2023-03-14T15:39:05.608000Z"
      }
    },
    "surveys": [
      {
        "survey_location_url": "http://preview.mailersend.com/email/643e785e1ad4b461a307e5d2#ml-survey-link-5",
        "survey_id": "4",
        "question_id": "5",
        "question_index": 0,
        "question_type": "intro",
        "question": "We value your feedback.",
        "next_question_index": 1,
        "answers": [
          {
            "answer": "1",
            "answer_id": "1"
          }
        ],
        "rules": [
          {
            "$$hashKey": "object:3113",
            "answered": "answered_specific",
            "collapsed": true,
            "question_index": 1,
            "specific_answer": 1,
            "specific_answer_value": "Very Unsatisfied",
            "action": "skip_to_question",
            "action_question_index": 2
          }
        ],
        "correct_answers_rate": 0,
        "is_last_question": false
      },
      {
        "survey_location_url": "http://preview.mailersend.com/email/643e785e1ad4b461a307e5d2#ml-survey-link-5",
        "survey_id": "4",
        "question_id": "6",
        "question_index": 1,
        "question_type": "satisfaction_scale",
        "question": "How would you rate our new product line?",
        "next_question_index": 2,
        "answers": [
          {
            "answer": "5",
            "answer_id": "5",
            "image": "https://assets.mlcdn.com/ml/images/editor/survey/faces/color/5.png"
          }
        ],
        "rules": [
          {
            "$$hashKey": "object:3113",
            "answered": "answered_specific",
            "collapsed": true,
            "question_index": 1,
            "specific_answer": 1,
            "specific_answer_value": "Very Unsatisfied",
            "action": "skip_to_question",
            "action_question_index": 2
          }
        ],
        "correct_answers_rate": 0,
        "is_last_question": false
      },
      {
        "survey_location_url": "http://preview.mailersend.com/email/643e785e1ad4b461a307e5d2#ml-survey-link-5",
        "survey_id": "4",
        "question_id": "7",
        "question_index": 2,
        "question_type": "rating_scale",
        "question": "How likely are you to recommend our new products to a friend or colleague?",
        "next_question_index": 3,
        "answers": [
          {
            "answer": "2",
            "answer_id": "2"
          }
        ],
        "rules": [
          {
            "$$hashKey": "object:3113",
            "answered": "answered_specific",
            "collapsed": true,
            "question_index": 1,
            "specific_answer": 1,
            "specific_answer_value": "Very Unsatisfied",
            "action": "skip_to_question",
            "action_question_index": 2
          }
        ],
        "correct_answers_rate": 0,
        "is_last_question": true
      }
    ]
  }
}

An example of sender_identity.verified event:

{
  "type": "sender_identity.verified",
  "domain_id": "7z3m5jgrogdpyo6n",
  "created_at": "2023-07-05T08:14:27.281958Z",
  "webhook_id": "7z3m5jgrogdpyo6n",
  "url": "https://your-domain.com/webhook",
  "data": {
    "object": "sender_identity",
    "id": "1234asdfg6zqx8ko",
    "email": "info@example.com",
    "name": "Test Name",
    "reply_to_email": "replyto@example.com",
    "reply_to_name": "Test Reply To",
    "is_verified": true,
    "add_note": true,
    "personal_note": "Hi, I’m adding this email address to our sender identities in our MailerSend account so it can be shown as the From address in our emails. Can you click on the confirmation link, so that I can complete the process?",
    "domain": {
      "object": "domain",
      "id": "1234asdfg6zqx8ko",
      "name": "example.com",
      "created_at": "2023-01-01T12:00:00.000000Z",
      "updated_at": "2023-01-01T12:00:00.000000Z"
    }
  }
}

An example of maintenance.start event:

{
  "type": "maintenance.start",
  "domain_id": "1234asdfg6zqx8ko",
  "webhook_id": "1234asdfg6zqx8ko",
  "url": "https://your-domain.com/webhook",
  "created_at": "2023-01-01T11:30:00.000000Z"
}

An example of maintenance.end event:

{
  "type": "maintenance.end",
  "domain_id": "1234asdfg6zqx8ko",
  "webhook_id": "1234asdfg6zqx8ko",
  "url": "https://your-domain.com/webhook",
  "created_at": "2023-01-01T12:00:00.000000Z"
}

An example of inbound_forward.failed event:

{
  "type": "inbound_forward.failed",
  "domain_id": "2351ndgwr4zqx8ko",
  "created_at": "2023-12-13T18:38:34.681535Z",
  "webhook_id": "7z3m5jgrogdpyo6n",
  "url": "https://your-domain.com/webhook",
  "data": {
    "url": "https://your-domain.com/webhook-failed",
    "response_code": 404,
    "inbound_message": {
      "object": "inbound_message",
      "id": "6579f9b45070e80427c85478",
      "sender": {
        "email": "test@example.com"
      },
      "subject": "Test Email Inbound",
      "created_at": "2023-12-13T18:36:36.000000Z"
    },
    "inbound": {
      "object": "inbound",
      "id": "7z3m5jgrogdpyo6n",
      "domain_id": "2351ndgwr4zqx8ko"
    }
  }
}

An example of email_single.verified event:

{
  "type": "email_single.verified",
  "domain_id": "7nxe3yjmeq28vp0k",
  "created_at": "2025-03-05T09:23:12.654113Z",
  "webhook_id": "7nxe3yjmeq28vp0k",
  "url": "https://your-domain.com/webhook",
  "data": {
    "id": "67c817c1ed166ac8f0d4480a  ",
    "address": "test@email.com",
    "status": "completed",
    "result": "unknown",
    "error": null
  }
}

An example of email_list.verified event:

{
  "type": "email_list.verified",
  "domain_id": "7nxe3yjmeq28vp0k",
  "created_at": "2025-03-04T22:57:58.367113Z",
  "webhook_id": "7nxe3yjmeq28vp0k",
  "url": "https://your-domain.com/webhook",
  "data": {
    "id": "7nxe3yjmeq28vp0k",
    "name": "verify-test - Sheet1.csv",
    "total": 1,
    "verification_started": "2025-03-04T22:55:57.000000Z",
    "verification_ended": "2025-03-04T22:57:58.000000Z",
    "created_at": "2025-03-04T22:55:55.000000Z",
    "updated_at": "2025-03-04T22:57:58.000000Z",
    "status": {
      "name": "verified",
      "count": 1
    },
    "source": "file",
    "statistics": {
      "valid": 0,
      "catch_all": 0,
      "mailbox_full": 0,
      "role_based": 0,
      "unknown": 1,
      "syntax_error": 0,
      "typo": 0,
      "mailbox_not_found": 0,
      "disposable": 0,
      "mailbox_blocked": 0,
      "failed": 0,
      "not_verified": 0
    }
  }
}

An example of bulk_email.completed event:

{
  "type": "bulk_email.completed",
  "domain_id": "13zxk54v6gjy6v0m",
  "created_at": "2023-04-10T13:26:53.241599Z",
  "webhook_id": "1z3m5jgrogdpyo60",
  "url": "https://your-domain.com/webhook",
  "data": {
    "object": "bulk_email",
    "id": "07fd0d1b7a11d37a6fa0e87a",
    "state": "completed",
    "total_recipients_count": 4,
    "suppressed_recipients_count": 1,
    "suppressed_recipients": {
      "67fd0d1ceb8b67b82cdfca0f": {
        "to": [
          {
            "email": "test@some-email.com",
            "name": "Test User",
            "reasons": [
              "hard_bounced"
            ]
          }
        ]
      }
    },
    "validation_errors_count": 3,
    "validation_errors": {
      "message.0": {
        "template_id": [
          "The selected template_id is invalid."
        ]
      },
      "message.1": {
        "subject": [
          "The subject field is required. #MS42209"
        ]
      },
      "message.2": {
        "subject": [
          "The subject field is required. #MS42209"
        ]
      }
    },
    "messages_id": [
      "m7fd0d1ceb8b60b82cdfca01"
    ],
    "created_at": "2023-04-10T13:26:53.241599Z",
    "updated_at": "2023-04-10T13:26:53.241599Z"
  }
}

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);

import crypto from 'crypto'

const requestContent = '{request payload from webhook}';
const receivedSignature = 'signature from webhook header';
const signingSecret = 'your-secret-key';

const computedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(requestContent, 'utf8')
    .digest('hex');

return crypto.timingSafeEqual(
    Buffer.from(receivedSignature, 'hex'),
    Buffer.from(computedSignature, 'hex')
);

package webhook

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
)

func Handle(w http.ResponseWriter, r *http.Request) {
	// Read the entire request body
	bodyBytes, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Error reading request body", http.StatusBadRequest)
		return
	}
	defer r.Body.Close()

	// Restore the body so it can be read again by subsequent handlers
	r.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))

	// Create a new HMAC instance with your webhook secret
	secret := []byte("<WEBHOOK_SECRET>")
	hash := hmac.New(sha256.New, secret)

	// Write the body to the hash
	hash.Write(bodyBytes)

	// Calculate the expected signature
	expectedSignature := hex.EncodeToString(hash.Sum(nil))

	// Get the actual signature from the request header
	actualSignature := r.Header.Get("Signature")

	// Compare signatures using a constant-time comparison to prevent timing attacks
	if !hmac.Equal([]byte(expectedSignature), []byte(actualSignature)) {
		http.Error(w, "Invalid signature", http.StatusForbidden)
		return
	}

	// Signature is valid, process the webhook
	// Your webhook handling logic here...
	w.WriteHeader(http.StatusOK)
}

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.

Recommendations

To ensure reliable handling of webhooks, we recommend that you:

Send a 2xx response as soon as possible to confirm receipt of the webhook.
Move any further processing logic to an asynchronous (async) background job. This allows your endpoint to respond quickly and avoids potential timeouts or repeated attempts.

Useful tools

Webhook.siteopen in new window or Pipedream.comopen in new window: These allow you to see the contents of a webhook and inspect what's being sent.
Reqbin.comopen in new window: A versatile tool for testing webhooks and making HTTP requests in real time.

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.

Get a list of webhooks

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

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

Request parameters

Query Parameter	Type	Required	Limitations	Details
`domain_id`	`string`	yes

use MailerSend\MailerSend;

$mailersend = new MailerSend(['api_key' => 'key']);

$mailersend->webhooks->get('domain_id');

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

# Webhooks

# Webhooks overview

# Setup

# Available events

# Payload example

# Security

# Retrying failed webhooks

# Recommendations

# Useful tools

# FAQs

# Get a list of webhooks

# Request parameters

# Get a webhook

# Request parameters

# Create a webhook

# Request parameters

# Update a webhook

# Request parameters

# Delete a webhook

# Request parameters

Webhooks

Webhooks overview

Setup

Available events

Payload example

Security

Retrying failed webhooks

Recommendations

Useful tools

FAQs

Get a list of webhooks

Request parameters

Get a webhook

Request parameters

Create a webhook

Request parameters

Update a webhook

Request parameters

Delete a webhook

Request parameters