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

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

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

Вебхуки для возвратов срабатывают при возврате исходящих писем. Таким образом, ваш вебхук будет получать данные о жестких и мягких возвратах, блокировках и отклонениях писем как спама — категория возврата приходит в поле bounce_category.

Также можно сгенерировать тестовые возвраты, используя нашу песочницу «черную дыру». Это позволит вам безопасно протестировать вебхук, так как такие возвраты не повлияют на репутацию вашего домена.

Примечание: дата и время события передаются в полях event_time (московское время) и event_time_utc (UTC) в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС.

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

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

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

Через API

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

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

Haskimail отправляет на URL вебхука POST-запрос с заголовком Content-Type: application/json. Пример тела запроса показан справа. Все значения, кроме server_id, передаются строками.

event	string	Тип события: `bounced`.
recipient	string	Адрес получателя, письмо которому вернулось.
email	string	То же, что `recipient`.
bounce_category	string	Категория возврата: `hrd` — жесткий, `sft` — мягкий, `blk` — блокировка, `spm` — отклонено как спам. Соответствие типам API — в разделе «Типы возвратов».
code	string	Код ответа почтового сервера, например `550`.
error	string	Текст ответа почтового сервера.
description	string	То же, что `error`.
message_id	string	ID письма — `MessageID` из ответа на отправку.
campaign_id	string	Тег письма (`Tag`). Без тега — пустая строка.
custom_vars	string	Метаданные письма (`Metadata`) — строка с JSON. Если метаданные не передавались, строка пустая или поля нет.
server_id	integer	ID сервера, через который отправлено письмо.
stream_id	string	ID канала, через который отправлено письмо.
event_time	string	Когда получен возврат: московское время, `ГГГГ-ММ-ДД ЧЧ:ММ:СС`.
event_time_utc	string	То же время в UTC.
user_id	string	ID вашего аккаунта.
member_id	string	Служебный ID получателя.
secret	string	Подпись события — см. защиту вебхука.

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

{
  "event": "bounced",
  "recipient": "old-address@example.com",
  "email": "old-address@example.com",
  "message_id": "a41d7c9e2b6f4e0d8c3b5a1f9e7d2c60",
  "code": "550",
  "description": "550 5.1.1 The email account that you tried to reach does not exist",
  "error": "550 5.1.1 The email account that you tried to reach does not exist",
  "bounce_category": "hrd",
  "user_id": "48213",
  "campaign_id": "orders",
  "member_id": "0",
  "event_time": "2026-10-07 14:30:15",
  "event_time_utc": "2026-10-07 11:30:15",
  "secret": "5f2b0c1d9a7e4c3b8d6f1a2e3c4b5d6e",
  "custom_vars": "{\"order_id\":\"1042\"}",
  "server_id": 11834,
  "stream_id": "2081"
}

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

Если вы ведете разработку на локальной машине или у вашего обработчика еще нет публичного адреса, отправьте на него запрос, показанный справа: он повторяет то, что присылает Haskimail. Замените <your-url> на адрес обработчика.

Тестовое событие на уже настроенный URL можно отправить и из интерфейса: Сервер → Канал → «Вебхуки» → «Отправить тест».

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

curl <your-url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "event": "bounced",
  "recipient": "old-address@example.com",
  "email": "old-address@example.com",
  "message_id": "a41d7c9e2b6f4e0d8c3b5a1f9e7d2c60",
  "code": "550",
  "description": "550 5.1.1 The email account that you tried to reach does not exist",
  "error": "550 5.1.1 The email account that you tried to reach does not exist",
  "bounce_category": "hrd",
  "user_id": "48213",
  "campaign_id": "orders",
  "member_id": "0",
  "event_time": "2026-10-07 14:30:15",
  "event_time_utc": "2026-10-07 11:30:15",
  "secret": "5f2b0c1d9a7e4c3b8d6f1a2e3c4b5d6e",
  "custom_vars": "{\"order_id\":\"1042\"}",
  "server_id": 11834,
  "stream_id": "2081"
}'

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

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

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

Обзор

Интеграции

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

Справочник API

Вебхуки