Вебхуки

Как работают модульные вебхуки?

С помощью модульных вебхуков от HaskiMail вы можете получать уведомления в реальном времени о таких событиях, как возвраты, открытия и клики в виде HTTP POST-запросов на URL, который вы укажете. Вебхуки группируются по шести поддерживаемым типам событий: 1. Доставка 2. Открытие 3. Клик 4. Изменение подписки 5. Возвраты 6. Жалобы на спам Важно: вебхуки для возвратов и жалоб на спам недоступны для маркетинговых каналов отправки. С помощью модульных вебхуков вы можете: - Добавить до 10 вебхуков с любой комбинацией событий - Выбрать, какие события будут включены в каждый URL Этот полезный материал покажет, как добавить и протестировать URL вашего вебхука. Как добавить вебхук - Войдите в HaskiMail и откройте сервер, для которого хотите настроить вебхуки. - Выберите Канал отправки. - Перейдите в раздел Вебхуки. - Нажмите Добавить вебхук. - В поле URL вебхука введите URL, на который хотите получать события. При добавлении или редактировании вебхука необходимо указать тип события и действующий URL. Как протестировать вебхук Перед сохранением URL обязательно используйте кнопку Отправить тест, чтобы отправить тестовое событие на ваш URL вебхука. Если вы выбрали несколько событий для одного вебхука, вы можете выбрать событие для тестирования в выпадающем списке рядом с кнопкой Отправить тест. Примечание: вебхуки должны отвечать с кодом 2xx для успешной обработки. Как сохранить вебхук После успешного теста нажмите Сохранить вебхук внизу страницы. Теперь ваш вебхук настроен! Тестирование вебхуков с Postman Postman — это бесплатный клиент API, который вы можете использовать для управления и выполнения ваших API-запросов. С помощью Postman разработчики могут создавать, делиться, тестировать и документировать API, а также создавать и сохранять простые и сложные HTTP/HTTPS-запросы, а также читать их ответы. Postman отлично подходит для отправки макетных запросов на ваши URL вебхуков.

Как настроить вебхук для возвратов?

Вебхуки для возвратов от HaskiMail позволяют получать уведомления в реальном времени каждый раз, когда отправленное вами письмо вызывает возврат. Эти уведомления о возвратах отправляются в виде HTTP POST на URL, который вы укажете в настройках канала отправки сообщений HaskiMail. Уведомления вебхуков для возвратов включают информацию, такую как отправитель, получатель, тема письма и причина возврата. HTTP POST, содержащий информацию о возврате, отправляется в формате JSON: { "RecordType": "Bounce", "MessageStream": "transactional", "ID": 42, "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": "john@example.com", "From": "sender@example.com", "BouncedAt": "2019-11-05T16:33:54.9070259Z", "DumpAvailable": true, "Inactive": true, "CanActivate": true, "Subject": "Test subject", "Content": "<Full dump of bounce>" } Что можно делать с уведомлениями о возвратах? События вебхуков для возвратов можно использовать для различных целей, таких как: - Уведомление отправителей о возврате письма - Отслеживание тенденций возвратов - Предотвращение дальнейшей отправки на неверные адреса - Отслеживание адресов, которые вернулись, чтобы связаться с получателем через другой канал Как именно вы будете использовать уведомления о возвратах, зависит от вас. Вы можете разработать дополнительную функциональность в коде URL вебхука для обработки уведомлений о возвратах, которые вы получаете. Что нужно для получения уведомлений о возвратах? Прежде чем настроить URL вебхука для возвратов в настройках канала отправки, ознакомьтесь с нашей документацией, чтобы разработать код для получения событий вебхуков. Если вы не знакомы с получением HTTP POST-запросов, возможно, вам потребуется помощь разработчика для создания и хостинга приложения, которое будет получать и обрабатывать уведомления о возвратах. Как настроить URL вебхука для возвратов в HaskiMail? Когда ваш URL будет хоститься и готов к получению и обработке уведомлений о возвратах, вы можете настроить его в настройках канала отправки HaskiMail. - Выберите свой сервер и затем канал отправки, для которого хотите получать уведомления о возвратах. - Перейдите в раздел Вебхуки и нажмите кнопку Добавить вебхук. - Введите URL вебхука для возвратов в поле URL Вебхука. - После ввода URL, отметьте флажок для возврата и протестируйте URL вебхука, чтобы убедиться, что все работает. - Сохраните изменения после тестирования. Тестирование возвратов в HaskiMail HaskiMail предоставляет black hole домен, который позволяет протестировать все возможные ответы на возвраты, и каждый из этих ответов вызовет вебхук возврата. Письма, отправленные на этот домен, не повлияют на вашу репутацию отправителя. Заключение Теперь вы готовы воспользоваться этим мощным инструментом и начать использовать вебхуки для возвратов, чтобы получать уведомления о возвратах для вашего канала отправки. Если у вас возникнут вопросы, не стесняйтесь обращаться к нам, и мы поможем!

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

Вместо того чтобы запрашивать статус доставки через API HaskiMail или использовать наш интерфейс, HaskiMail предлагает вебхуки для доставки. Этот вебхук отправляет обновления в реальном времени (в формате JSON), когда сообщение доставлено. Вы можете настроить URL вебхука для доставки с помощью нашего API и интерфейса. Настройка URL вебхука для доставки через интерфейс HaskiMail - Войдите в HaskiMail, выберите сервер, затем канал отправки и перейдите на вкладку «Вебхуки». - Нажмите «Добавить вебхук» и введите URL вебхука в поле «URL Вебхука». - Выберите флажок DELIVERED и перед сохранением изменений обязательно протестируйте вебхук, чтобы убедиться, что он работает. Настройка URL вебхука для доставки при создании нового сервера через API - Endpoint: https://api.haskimail.ru/servers - Метод HTTP: POST - Заголовки: - Accept: application/json - Content-Type: application/json - X-HaskiMail-Account-Token: ваш API токен аккаунта - Тело: { "Name": "Delivery Webhook Test Server", "Color": "blue", "SmtpApiActivated": true, "RawEmailEnabled": false, "InboundHookUrl": null, "BounceHookUrl": null, "OpenHookUrl": null, "PostFirstOpenOnly": false, "TrackOpens": false, "InboundDomain": null, "InboundSpamThreshold": 5, "DeliveryHookUrl": "http://yourdomain.com/webhooks/delivery" } Настройка URL вебхука для доставки для существующего сервера через API: - Endpoint: https://api.haskimail.ru/server - Метод HTTP: PUT - Заголовки: - Accept: application/json - Content-Type: application/json - X-HaskiMail-Server-Token: ваш API токен сервера - Тело: { "DeliveryHookUrl": "http://yourdomain.com/webhooks/delivery" } Пример события вебхука для доставки: Когда вы получите событие вебхука для доставки на свой URL, оно будет иметь следующий формат: { "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483", "Recipient": "john@example.com", "DeliveredAt": "2019-08-01T13:28:10.2735393-04:00", "Details": "Test delivery webhook details", "Tag": "welcome-email", "ServerId": 23, "Metadata": { "a_key": "a_value", "b_key": "b_value" }, "RecordType": "Delivery" } MessageID: ID сообщения, связанное с письмом. Recipient: Адрес получателя, который получил письмо. Tag: Если вы добавили тег к письму при отправке, он будет отображаться в JSON. DeliveredAt: Время, когда письмо было принято почтовым сервером получателя. Details: Полные данные о том, что ответил сервер получателя. Интеграция Теперь, когда вы знаете, как настроить вебхуки для доставки, вы можете использовать информацию о доставке в своем приложении, чтобы в реальном времени отслеживать статус доставки писем, отправленных вашими пользователями. Для получения дополнительной информации, обратитесь к нашей документации по вебхукам для доставки.

Как автоматически уведомить отправителей о возврате письма?

Когда вы используете HaskiMail для отправки писем, вся информация о возвратах отправляется в наш return-path, чтобы она была доступна на вашей странице активности, а также через наш API и вебхуки. Однако, в отличие от того, как это работает в других системах, подробности о возврате не отправляются на адрес, указанный в заголовке «From», для писем, которые были возвращены. Эта статья поможет вам использовать вебхуки возвратов, чтобы отправлять письма с информацией о возврате исходному отправителю. Требования Прежде чем автоматически уведомить отправителей о возврате письма, необходимо настроить ваш URL вебхука для возврата на сервере HaskiMail и удостовериться, что он успешно получает уведомления о возвратах. Если вы не завершили этот шаг, вернитесь к этой статье, когда настройка вебхука будет работать корректно. Документация по нашему вебхуку возвратов доступна здесь. Получение адреса From Когда вы получаете уведомление о возврате через вебхук, оно будет иметь следующий формат JSON: { "ID": 42, "Type": "HardBounce", "TypeCode": 1, "Name": "Hard bounce", "Tag": "Test", "MessageID": "883953f4-6105-42a2-a16a-77a8eac79483", "ServerId": 23, "Description": "Сервер не смог доставить ваше письмо (например, неизвестный пользователь, почтовый ящик не найден)", "Details": "Тестовые детали возврата", "Email": "john@example.com", "From": "sender@example.com", "BouncedAt": "2014-08-01T13:28:10.2735393-04:00", "DumpAvailable": true, "Inactive": true, "CanActivate": true, "Subject": "Тема теста" } Уведомление отправителя Так как вы уже отправляете письма через HaskiMail, вы, вероятно, знакомы с тем, как использовать наш API или SMTP для отправки сообщений. Вы можете использовать любые данные для уведомления отправителей о возврате, но мы рекомендуем включить, как минимум, следующие данные: - Email: Адрес получателя, который вызвал возврат - From: Адрес отправителя (куда будет отправлено уведомление о возврате) - Details: Подробности о возврате - Description: Описание возврата - Subject: Тема письма, которое вернулось