Вебхук для возвратов

Что такое вебхук для возвратов? #

Одна из причин использовать Haskimail — это автоматическая обработка всех возможных возвратов от почтовых серверов. Однако вашему приложению все равно нужна информация об этих возвратах в удобном формате. Вы можете использовать API возвратов, чтобы запрашивать (pull) данные, но для многих приложений проще настроить вебхук. С его помощью Haskimail будет сам отправлять (push) данные о возвратах в ваше приложение сразу же, как только они произойдут. Вебхук для возвратов отправляет данные в ваше приложение в простом для парсинга формате JSON сразу после того, как Haskimail обработает возврат.

Вебхуки для возвратов срабатывают при возврате исходящих писем. Таким образом, ваш вебхук будет получать данные о жестких (Hard Bounce) и мягких (Soft Bounce) возвратах, возвратах по причине недоставки (Undeliverable) и т.д.

Примечание: Дата и время в поле BouncedAt передаются в формате ISO 8601.

Настройка URL вебхука для возвратов #

Через веб-интерфейс Haskimail

Войдите в аккаунт Haskimail, выберите нужный Сервер и Канал, а затем перейдите на вкладку «Вебхуки». Нажмите «Добавить вебхук», введите URL в поле «URL вебхука» и установите флажок напротив события «Возвраты» (Bounce).

Через API

Вы можете настроить триггер Bounce с помощью API Вебхуков как при создании нового вебхука, так и при редактировании уже существующего.

Данные вебхука для возвратов#

Справа показан пример полного JSON-документа, который будет отправлен POST-запросом на ваш URL вебхука. Ниже приведено краткое описание некоторых ключевых полей:

message_id — идентификатор сообщения.
event — BOUNCED
custom_vars — пользовательские метаданные, которые были добавлены в письмо.
recipient — email-адрес, на котором произошел возврат.
code — код возврата (из ответа сервера).
error — текст возврата (из ответа сервера).
bounce_category — категория возврата (hrd, sft).
campaign_id — значение Tag, переданное при отправке.
event_time — временная метка, когда произошел возврат.
server_id — id сервера, через который было отправлено письмо.
stream_id — id канала, через который было отправлено письмо.

Пример JSON данных вебхука

{
  "event": "BOUNCED",
  "message_id": "883953f4-6105-42a2-a16a-77a8eac79483",
  "bounce_category": "hrd",
  "code": 550,
  "error": "No such user! 1771485007-5AVCdxW9emI0-GiWrlUXb",
  "campaign_id": "Test",
  "custom_vars" : {
    "a_key" : "a_value",
    "b_key": "b_value"
   },
  "server_id": 23,
  "stream_id": 25,
  "recipient": "ivan@example.com",
  "event_time": "2019-11-05 16:33:54"
}

Как можно использовать данные о возвратах #

Существует множество способов использования данных, которые предоставляет вебхук для возвратов:

Мгновенно предлагать пользователям исправить их email, если письмо, отправленное при регистрации, вернулось.
Использовать данные для создания статистики, специфичной для вашего приложения.
Использовать данные для повторной активации email-адресов после жестких возвратов с помощью API активации возвратов.
Использовать данные для уведомления вашей команды, когда определенные письма возвращаются.