Webhooks for transactional emails

If you are currently using this webhook, please migrate to V2 by January 30, 2026, to ensure uninterrupted access, enhanced performance, and continued support.

Webhooks are typically used to connect two different applications. When an event occurs on the trigger application, it serializes the data about the respective event and sends it in real time to a Webhook URL from the action application.

Webhooks offer several features that enhance functionality and data management:

Track user-level details such as delivered, open, click, unsubscribe, and marked as spam.
Synced and consistent database of real-time user interactions with emails.
Webhooks email reporting (invalid email IDs, bounce backs) for improved list/database hygiene.
Automatic and manual user segmentation using real-time email events in your own CRM.

Set Up Webhook

You can set up the callback within the body payload to receive webhook events for your transactional emails by adding the following sample object at the end of the payload:

"callback": {
"url": "https://webhook.site/123abc-4567-890d-a1b2-3c4d5e6f7g",
"secret": "secret"
}

You can also set up an optional secret key in the payload to validate the webhook events being sent to the callback URL.

Please note that Secret key is an optional property that users can use while sending an email to verify the webhook events. The key used in the payload is encrypted with the webhook event using SHA1 algorithm. The computed HMAC is sent back with the webhook events in X-INS-AUTH header. Users can verify the webhook events by decrypting the value returned under X-INS-AUTH.

your title goes here

X-INS-AUTH header gets the result of encrypting the event body with the provided secret key as its value.

Your title goes here

The content is encoded with UTF-8 on our end. Therefore, we suggest using the same encoding when reading the data stream to prevent interoperability issues. For example, reading with UTF-16 or Unicode might create problems with Unicode characters. The programming language we are using implements JSON encoding as covered in sections 8.1 and 8.2 of the RFC standard.

Webhook Events

Whenever there is an event, webhook events will notify a URL of your choice via HTTPS POST. Webhook events will provide information about the event, and return a unique message ID (msg-id) generated to map the emails associated with the event while also hitting the API. Webhook events will be delivered to the provided endpoint and encrypted by using the secret key (if applicable) after the first email is sent.

The following are some of the most essential events:

Processed
Delivered
Blocked
Bounced
Email Open
Email Click
Spam Complaint
Dropped
Deferred

Processed

A processed event is triggered when a message has been received and is ready to be delivered to the recipient.

{
  "email": "sample@mail.com",
  "event": "processed",
  "sender_domain": "@sender.domain",
  "msg-id": "389c9e3a-6c39-4e0e-b559-ab174321fdc5",
  "property1": "string",
  "property2": "string",
  "timestamp": 1603813206
}

Delivered

A delivered event is triggered when a message is delivered to the recipient.

{
  "email": "sample@mail.com",
  "event": "delivered",
  "sender_domain": "@sender.domain",
  "ip": "111.22.333.444",
  "msg-id": "bd12fbea-f982-4d8d-8378-04b23125a185",
  "product1": "laptop",
  "product2": "phone",
  "timestamp": 1614700548
}

Blocked

A blocked event is triggered when a soft bounce (blocked) is received from the receiving server for a specific email ID. The reason for the soft bounce will also return in the payload.

{
  "email": "sample@mail.com",
  "event": "bounce",
  "event_type": "blocked",
  "sender_domain": "@sender.domain",
  "msg-id": "51144895-a93e-4983-98be-29--34df377aa52c",
  "property1": "string",
  "property2": "string",
  "reason": "error dialing remote address: dial tcp 111.22.333.444:0->55.666.777.888:99: i/o timeout",
  "timestamp": 1603813274
}

Bounced

A bounced event is triggered when a hard bounce is received from the receiving server for a specific email ID. The reason for the hard bounce will also return in the payload.

{
  "email": "sample@mail.com",
  "event": "bounce",
  "sender_domain": "@sender.domain",
  "msg-id": "c289bc4f-410f-2b83-a76e-f75f5cc67afd",
  "reason": "unable to get mx info: lookup <nil>: unrecognized address",
  "product1": "laptop",
  "product2": "phone",
  "timestamp": 1563890445
}

Email Open

An open event is triggered when a recipient opens an email.

{
  "email": "sample@mail.com",
  "event": "open",
  "sender_domain": "@sender.domain",
  "ip": "11.222.33.444",
  "msg-id": "bd16fbea-f982-2d8d-8378-04b12125a185",
  "product1": "laptop",
  "product2": "phone",
  "timestamp": 1614700573,
  "url_offset": null,
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.150 Safari/537.36"
}

Email Click

A link click event is triggered when a recipient clicks a link in the email. The clicked link will also be sent with the webhook event.

{
  "email": "sample@mail.com",
  "event": "click",
  "sender_domain": "@sender.domain",
  "ip": "11.222.33.444",
  "link_clicked": "https://www.mywebsite.com/link-html",
  "msg-id": "bd16fbea-f982-4d4d-8378-04b12125a185",
  "product1": "laptop",
  "product2": "phone",
  "timestamp": 1614700422,
  "url_offset": {
    "index": 0,
    "type": "html"
  },
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.150 Safari/537.36"
}

Spam Complaint

A spam-complaint event is triggered when a recipient marks an email as spam.

{
  "email": "sample@mail.com",
  "event": "spam_complaint",
  "sender_domain": "@sender.domain",
  "msg-id": "c383bc4f-640f-4b83-a76e-f75f3cc67afd",
  "product1": "laptop",
  "product2": "phone",
  "timestamp": 1563890445
}

Dropped

A drop event occurs when you try to send a message to an email address listed on one of the suppression lists: bounces, unsubscribes, spam reports, and invalid emails.

{
  "email": "sample@mail.com",
  "event": "dropped",
  "sender_domain": "@sender.domain",
  "msg-id": "51154935-a93e-4983-98be-29df237aa52c",
  "property1": "string",
  "property2": "string",
  "reason": "Bounced Address",
  "timestamp": 1603812824
}

Deferred

A deferred event occurs when a server rejects the message temporarily.

{
  "email": "sample@mail.com",
  "event": "deferred",
  "sender_domain": "@sender.domain",
  "msg-id": "51125925-a93e-4983-98be-29df277aa72c",
  "property1": "string",
  "property2": "string",
  "timestamp": 1603812854
}