Как подключить вебхуки для транзакционных писем
Webhook — механизм получения уведомлений об определенных событиях. Вы можете настроить оповещения себе в систему о доставляемости писем и активности подписчиков.
Как создать вебхук
Чтобы подключить вебхуки транзакционных писем SMTP, перейдите в раздел Настройки аккаунта на вкладку API и нажмите Создать webhook.
Активируйте отслеживание рассылок SMTP, если оно было отключено.
Укажите URL вашего обработчика, на которую нужно отправлять события. Также отметьте, какие именно события нужно передавать.
Список событий, по которым срабатывает webhook в сервисе SMTP относительно отправки письма:
| Доставлено (Delivered) | Письмо успешно доставлено к получателю. |
| Не доставлено (Not delivered) | Письмо не удалось доставить к получателю. |
| Открыто (Open) | Получатель открыл письмо. |
| Переход по ссылке (Click on a link) | Получатель нажал на ссылку, содержащуюся в письме. |
| Отмечено как спам (Marked as spam) | Получатель обозначил письмо как спам и отписался |
| Отписался (Unsubscribed) | Получатель отписался от получения последующих писем. |
| Переподписался (Resubscribed) | Отписанный ранее получатель подтвердил подписку в письме, какое было отправлено через метод Повторно подписаться на получателя. |
| Ошибка Hard bounce (Hard bounces) | Письмо не удалось доставить из-за постоянной ошибки. Причиной может быть несуществующая или невалидно электронов адрес. |
| Ошибка Soft bounce (Soft bounces) | Письмо не удалось доставить по временной ошибке. Причины могут включать в себя переполненный почтовый ящик или временные проблемы с сервером получателя. |
Формат отправляемых данных
Вебхук срабатывает каждые 30 секунд или если собрано 500 событий для отправки.
При срабатывании вебхука SendPulse отправляет на указанный URL POST запрос с JSON типом данных.
Данные пересылаются в следующем формате:
[
{
"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": 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"
},
]
Форматы запросов, в зависимости от события
Доставлено:
[
{
"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"
}
]
Не доставлено:
[
{
"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"
}
]
Открыто:
[
{
"event": "opened",
"timestamp": 1490962764,
"message_id": 1149317311,
"recipient": "doe.john@sendpulse.com",
"sender": "john.doe@sendpulse.com",
"subject": "utf8_hello_world"
}
]Переход по ссылке:
[
{
"event": "clicked",
"timestamp": 1490964928,
"message_id": 1149317311,
"recipient": "doe.john@sendpulse.com",
"sender": "john.doe@sendpulse.com",
"subject": "utf8_hello_world"
}
]Отписался:
[
{
"event": "unsubscribed",
"recipient": "john.doe@sendpulse.com",
"sender": "doe.john@sendpulse.com",
"subject": "hello world"
}
]
Переподписка:
[
{
"timestamp":1717500409,
"message_id":"",
"recipient":"john.doe@sendpulse.com",
"event":"resubscribed",
"subject":""
}
]
Отмечено как спам:
[
{
"event": "spam_by_user",
"timestamp": 1490964607,
"message_id": 1145317311,
"recipient": "doe.john@sendpulse.com",
"sender": "john.doe@sendpulse.com",
"subject": "utf8_hello_world"
}
]
Получен 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"
}
]Получен 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"
}
]
Пример скрипта, принимающего запрос, на языке PHP:
<?php
$json_string = file_get_contents('php://input');
$data_array = json_decode($json_string, true);
?>
Обновлено: 10.06.2024
или