Аккаунт
Выйти

Обзор

Интеграции

Руководство пользователя

Справочник API

Вебхуки

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

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

Одна из причин использовать 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 вебхука. Ниже приведено краткое описание некоторых ключевых полей:

  • ID — этот идентификатор можно использовать для выполнения различных запросов к API возвратов. Это значение типа int64.
  • Type — классификация, присвоенная возврату сервисом Haskimail. Все типы возвратов перечислены на странице справочника по API возвратов. Обратите внимание, что для жалоб на спам, отписок/подписок и ручных деактиваций существуют отдельные вебхуки; они не вызывают срабатывание вебхука для возвратов.
     
  • Metadata — пользовательские метаданные, которые были добавлены в письмо.
  • Email — email-адрес, на котором произошел возврат.
  • From — адрес отправителя исходного письма, вызвавшего возврат.
  • BouncedAt — временная метка, когда произошел возврат.
  • Inactive — показывает, привел ли этот возврат к деактивации email-адреса.
  • CanActivate — показывает, можно ли повторно активировать этот адрес. 
     
  • Content (необязательно) — полное содержимое письма, вызвавшего возврат. По умолчанию эта опция отключена, но ее можно включить.

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

{
  "RecordType": "Bounce",
  "MessageStream": "outbound",
  "ID": 4323372036854775807,
  "Type": "HardBounce",
  "TypeCode": 1,
  "Name": "Hard bounce",
  "Tag": "Test",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "Metadata" : {
    "a_key" : "a_value",
    "b_key": "b_value"
   },
  "ServerID": 23,
  "Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
  "Details": "Test bounce details",
  "Email": "ivan@example.com",
  "From": "masha@example.com",
  "BouncedAt": "2019-11-05T16:33:54.9070259Z",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": true,
  "Subject": "Test subject",
  "Content": "<Full dump of bounce>"
}

Тестирование вебхука для возвратов с помощью curl #

Если вы ведете разработку на локальной машине или у вас нет публичного URL для вашего API, вы можете использовать пример POST-запроса, показанный справа. Замените <your-url> на API-маршрут, который вы хотите использовать в качестве URL вашего вебхука. Этот curl-запрос позволит вам убедиться, что ваш URL может принимать запросы в том же JSON-формате, который будут использовать серверы Haskimail.

Пример вызова curl

curl <your-url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "ID": 4323372036854775807,
  "Type": "HardBounce",
  "TypeCode": 1,
  "Name": "Hard bounce",
  "Tag": "Test",
  "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
  "ServerID": 23,
  "Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
  "Details": "Test bounce details",
  "Email": "ivan@example.com",
  "From": "masha@example.com",
  "BouncedAt": "2014-08-01T13:28:10.2735393-04:00",
  "DumpAvailable": true,
  "Inactive": true,
  "CanActivate": true,
  "RecordType": "Bounce",
  "Subject": "Test subject"
}'

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

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

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