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

Вебхук возвратов сообщает в реальном времени о каждом письме, которое не удалось доставить. Haskimail отправляет HTTP POST-запрос с JSON на URL, указанный в настройках канала отправки.

Вебхук возвратов работает и в транзакционных, и в маркетинговых каналах.

Пример тела запроса:

{
  "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"
}

Основные поля:

• event — тип события, для возврата всегда bounced;
• recipient — адрес, на который не удалось доставить письмо;
• bounce_category — тип возврата: hrd — жёсткий возврат, sft — мягкий возврат, blk — блокировка сервером получателя (по его политике или из-за репутации отправителя), spm — письмо отклонено спам-фильтром из-за содержания;
• code и error — код и текст ответа почтового сервера;
• message_id — ID письма из ответа на отправку;
• campaign_id — тег письма;
• custom_vars — метаданные письма в виде строки с JSON;
• event_time и event_time_utc — время события по Москве и в UTC;
• secret — подпись для проверки подлинности запроса.

Все значения, кроме server_id, передаются строками. Полное описание полей — в документации.

Как использовать вебхук возвратов

• Сообщать отправителю или пользователю, что письмо не доставлено.
• Помечать недействительные адреса в своей базе и не отправлять на них письма.
• Следить за ростом возвратов.
• Связываться с получателем другим способом, чтобы узнать новый адрес.

Как подключить вебхук

Сначала подготовьте на своём сервере обработчик, который принимает POST-запросы с JSON и отвечает кодом 2xx. Затем:

1. Откройте сервер и канал отправки.
2. Перейдите на вкладку Вебхуки и нажмите Добавить вебхук.
3. Укажите URL в поле URL вебхука.
4. Отметьте событие BOUNCED (возвраты) и нажмите Отправить тест.
5. Если тест прошёл успешно, сохраните вебхук.

Как Haskimail повторяет отправку и как защитить вебхук — в статье «Модульные вебхуки».

Как протестировать

Отправьте письмо на один из тестовых адресов, например hardbounce@bounce-testing.haskimail.ru или softbounce@bounce-testing.haskimail.ru. Haskimail создаст тестовый возврат и вызовет вебхук. Такие письма не влияют на вашу репутацию. Все тестовые адреса — в статье «Как тестировать письма перед отправкой».