The Webhooks mechanism allows you to receive POST requests to a specified URL when events occur related to:
-
Single messages
-
Template-based messages
-
Single SMTP messages
Webhook Payload Structure
{
"message": {
"id": 1
},
"event": {
"name": "clicked",
"timestamp": 1539062173,
"data": {
"url": "https://example.com"
}
}
}
Key Fields:
-
message.id: Identifier of the message associated with the event. -
event: Contains event details:-
name: Type of event (see below). -
timestamp: Unix timestamp of the event. -
data: Additional context (e.g., URL forclickedevents).
-
Events type
| Event | Description |
|---|---|
delivered |
Message successfully delivered. |
opened |
Message was opened by the recipient. |
clicked |
Recipient clicked a link (event.data.url contains the URL). |
unsubscribed |
Recipient unsubscribed. |
complained |
Recipient marked the message as spam. |
skipped |
Message not sent (e.g., recipient previously unsubscribed/complained). |
soft_bounced |
Message temporarily rejected by recipient’s server (may retry). |
hard_bounced |
Message permanently rejected by recipient’s server. |
Enabling Webhooks
JSON Request Example:
{
"url":"https://example.com/some/path"
}HTTP Request Example:
curl -X POST https://api.msndr.net/v1/email/webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Uses POST and /email/webhook endpoint
curl -X POST https://api.msndr.net/v1/email/webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'Successful Response:
{
"url":"https://example.com/some/path"
}
|
Parameter |
Description |
Required |
|
url |
Your endpoint for event data |
yes |
Retrieving Webhook Settings
HTTP request example:
curl -X GET https://api.msndr.net/v1/email/webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Uses GET and /email/webhook endpoint
Successful response:
{
"url":"https://example.com/some/path"
}
Returns the currently configured webhook URL.
Disabling Webhooks
json Request Example:
{
"url":"https://example.com/some/path"
}
HTTP Request Example:
curl -X DELETE https://api.msndr.net/v1/email/webhook \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN'
Uses DELETE method and /email/webhook endpoint
