How to enable webhooks for transactional emails
A webhook is a mechanism for receiving notifications about certain events. You can set up notifications about email deliverability and subscriber activity.
How to create a webhook
To connect SMTP Webhooks go to the Account Settings section in the API tab and click Create webhook.
Specify the URL of your handler where you send events, and mark which events you want to send.
The following events trigger webhooks to send emails in the SMTP service:
| Delivered (Delivered) | The email was successfully delivered to its recipient. |
| Not delivered (Not delivered) | The email could not be delivered to its recipient. |
| Openly (Open) | The recipient opened the email. |
| Jump to the link (Click on a link) | The recipient clicked a link in the email. |
| Marked as spam (Marked as spam) | The recipient marked the email as spam and unsubscribed. |
| Signed off (Unsubscribed) | The recipient has unsubscribed from further emails. |
| Resubscribed (Resubscribed) | The previously unsubscribed recipient confirmed their subscription in the email that was sent through the Resubscribe a recipient method. |
| Hard bounce error (Hard bounces) | The email could not be delivered due to a permanent error. The reason may be a non-existent or invalid email address. |
| Soft bounce error (Soft bounces) | The email could not be delivered due to a temporary error. Reasons may include an full inbox or temporary issues with the recipient's server. |
Send data format
Webhook is triggered every 30 seconds or if SendPulse has collected 500 events to send.
When the webhook is triggered, SendPulse sends a POST request with JSON data type to the specified URL.
Data is sent in the following format:
[
{
"event": "event_name",
"timestamp": 1490954061,
"message_id": 1149317311,
"recipient": "john.doe@sendpulse.com",
"sender": "doe.john@sendpulse.com",
"subject": "hello world"
}
]If there are several events, then they will be grouped into one or several requests:
[
{
"event": "event_name",
"timestamp": 1490954061,
"message_id": 1149317311,
"recipient": "john.doe@sendpulse.com",
"sender": "doe.john@sendpulse.com",
"subject": "hello world"
},
{
"event": "event_name",
"timestamp": 1490954062,
"message_id": 1149317311,
"recipient": "john.doe@sendpulse.com",
"sender": "doe.john@sendpulse.com",
"subject": "hello world"
},
{
"event": "event_name",
"timestamp": 1490954063,
"message_id": 1149317311,
"recipient": "john.doe@sendpulse.com",
"sender": "doe.john@sendpulse.com",
"subject": "utf8_hello_world"
},
]Request formats, depending on the event
Delivered:
[
{
"smtp_server_response_code": "250",
"smtp_server_response_subcode": "",
"sender": "john.doe@sendpulse.com",
"smtp_server_response": "custom_text_response_from_recipients_server",
"timestamp": 1490953933,
"message_id": 1149317311,
"recipient": "doe.john@sendpulse.com",
"event": "delivered",
"subject": "utf8_hello_world"
}
]
Not delivered:
[
{
"smtp_server_response_code": "554",
"smtp_server_response_subcode": "5.7.1",
"sender": "john.doe@sendpulse.com",
"smtp_server_response": "custom_text_response_from_recipients_server",
"timestamp": 1490956117,
"message_id": 1149317311,
"recipient": "doe.john@sendpulse.com",
"event": "undelivered",
"subject": "utf8_hello_world"
}
]Open:
[
{
"event": "opened",
"timestamp": 1490962764,
"message_id": 1149317311,
"recipient": "doe.john@sendpulse.com",
"sender": "john.doe@sendpulse.com",
"subject": "utf8_hello_world"
}
]
Folowing a link:
[
{
"event": "clicked",
"timestamp": 1490964928,
"message_id": 1149317311,
"recipient": "doe.john@sendpulse.com",
"sender": "john.doe@sendpulse.com",
"subject": "utf8_hello_world"
}
]
Unsubscribed:
[
{
"event": "unsubscribed",
"recipient": "john.doe@sendpulse.com",
"sender": "doe.john@sendpulse.com",
"subject": "hello world"
}
]Resubscribed:
[
{
"timestamp":1717500409,
"message_id":"",
"recipient":"john.doe@sendpulse.com",
"event":"resubscribed",
"subject":""
}
]
Reported as spam:
[
{
"event": "spam_by_user",
"timestamp": 1490964607,
"message_id": 1145317311,
"recipient": "doe.john@sendpulse.com",
"sender": "john.doe@sendpulse.com",
"subject": "utf8_hello_world"
}
]Received soft bounce:
[
{
"smtp_server_response_code": 550,
"smtp_server_response_subcode": "5.1.0",
"task_id": 17076325,
"smtp_server_response": " vch15@i.ua MX: mx23.i.ua RESP: Mailbox over quota. See http://mail.i.ua/err/4/",
"timestamp": 1658998170,
"event": "soft_bounces",
"email": "example@example.com"
}
]Received hard bounce:
[
{
"smtp_server_response_code": 550,
"smtp_server_response_subcode": "5.1.1",
"task_id": 17076325,
"smtp_server_response": " example@example.com MX: mx.dereck.cn.ua RESP: 5.1.1 <example@example.com>: Recipient address rejected: User unknown in local recipient table",
"timestamp": 1658998170,
"event": "hard_bounces",
"email": "example@example.com"
}
]
An example of a script that accepts a request in PHP:
<?php
$json_string = file_get_contents('php://input');
$data_array = json_decode($json_string, true);
?>
Last Updated: 10.06.2024
or