Вебхук о доставке

Что такое вебхук о доставке? #

Вебхук о доставке — это способ, которым Haskimail уведомляет ваше приложение об успешной доставке письма на сервер получателя. Это может быть полезно в самых разных ситуациях: например, чтобы предоставлять вашим клиентам информацию о доставке в реальном времени, измерять, сколько времени требуется письму, чтобы дойти до почтового ящика, или просто для аудита.

В Haskimail письмо считается успешно доставленным, когда почтовый сервер получателя возвращает ответ «ОК» после попытки доставки. Когда это происходит, Haskimail добавляет подтверждение о доставке для этого конкретного письма (и конкретного получателя, так как их может быть несколько). Одновременно с этим, если вебхук включен, на URL вашего вебхука о доставке отправляется POST-запрос. Обратите внимание, что в этот момент письмо покидает зону ответственности Haskimail, и сервер-получатель еще должен доставить письмо в почтовый ящик пользователя. Обычно это происходит мгновенно, но в редких случаях, например, при наличии внутреннего файрвола, письма могут быть поставлены в очередь сервером-получателем.

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

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

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

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

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

Через API

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

Данные вебхука о доставке #

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

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

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

{ 
	  "event": "DELIVERED",
	  "message_id": "883953f4-6105-42a2-a16a-77a8eac79483",
	  "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-уведомлениями.
Использовать данные для анализа скорости доставки ваших писем.