Как подключить вебхуки для транзакционных писем
Webhook — механизм получения уведомлений об определенных событиях. Вы можете настроить оповещения себе в систему о доставляемости писем и активности подписчиков.
Как создать вебхук
Чтобы подключить вебхуки транзакционных писем SMTP, перейдите в раздел Настройки аккаунта на вкладку API и нажмите Создать webhook.
Укажите 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
или