Вебхук для входящих писем

Что такое вебхук для входящих? #

У каждого сервера Haskimail есть входящий канал и свой входящий адрес вида {hash}@inbound.haskimail.ru. Haskimail принимает письма на этот адрес, разбирает их и отправляет POST-запросом на URL вашего вебхука в формате JSON: отправитель, получатели, тема, текст и HTML, заголовки и вложения.

Так удобно обрабатывать ответы клиентов, создавать тикеты поддержки из писем, принимать файлы по почте и строить любые сценарии, где приложению нужно получать email.

MailboxHash. Всё, что стоит в адресе после «+», приходит в поле MailboxHash: письмо на {hash}+ticket-42@inbound.haskimail.ru придёт с "MailboxHash": "ticket-42". Подставляйте такой адрес в Reply-To, чтобы связать ответ с заказом, тикетом или пользователем.
Свой домен. Добавьте поддомену MX-запись inbound.haskimail.ru (приоритет 10) и укажите его в настройках входящего канала — письма на любой адрес этого домена будут приходить на вебхук.
Правила блокировки и спам-фильтр. Письма от заблокированных отправителей или с оценкой спама выше порога получают статус Blocked и на вебхук не отправляются. Их можно пропустить вручную в интерфейсе или через API.
Хранение. Входящие письма хранятся 45 дней и доступны во вкладке «Активность» канала и через API Сообщений.

Каждое обработанное входящее письмо учитывается в лимите писем тарифа, как исходящее. Заблокированные письма не учитываются.

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

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

Выберите сервер, откройте канал «Входящий по-умолчанию» и перейдите на вкладку «Настройки». Укажите URL в поле «URL вебхука» и нажмите «Сохранить изменения». Кнопка «Проверить вебхук» отправит на URL пример JSON.

Для HTTP Basic-авторизации укажите логин и пароль в адресе: https://user:pass@example.ru/haski/inbound.

Через API

Передайте поле InboundHookUrl при создании или редактировании сервера. Там же настраиваются InboundDomain, InboundSpamThreshold и RawEmailEnabled.

Данные вебхука для входящих #

Формат совпадает с вебхуком входящих Postmark, поэтому подходят готовые обработчики и библиотеки для него. Запрос приходит с заголовком Content-Type: application/json.

MessageID — идентификатор письма в Haskimail (по нему работают детали, повтор и обход правил).
MessageStream — ID входящего канала.
From, FromName, FromFull — отправитель.
To, ToFull, Cc, CcFull, Bcc, BccFull — получатели из заголовков письма.
OriginalRecipient — адрес, на который письмо фактически доставлено.
MailboxHash — часть адреса после «+».
TextBody, HtmlBody — текст и HTML письма.
StrippedTextReply — текст ответа без цитаты предыдущего письма.
Headers — остальные заголовки, в том числе X-Spam-Score и Message-ID.
Attachments — вложения: Name, Content (base64), ContentType, ContentLength, ContentID (для картинок, встроенных в HTML).
RawEmail — исходник письма, если в настройках включено «Добавлять исходник письма».

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

{
  "FromName": "Иван Петров",
  "MessageStream": "2081",
  "From": "ivan@example.com",
  "FromFull": {
    "Email": "ivan@example.com",
    "Name": "Иван Петров",
    "MailboxHash": ""
  },
  "To": "\"Поддержка\" <451d9b70cf9364d23ff6f9d51d870251+ticket-42@inbound.haskimail.ru>",
  "ToFull": [
    {
      "Email": "451d9b70cf9364d23ff6f9d51d870251+ticket-42@inbound.haskimail.ru",
      "Name": "Поддержка",
      "MailboxHash": "ticket-42"
    }
  ],
  "Cc": "",
  "CcFull": [],
  "Bcc": "",
  "BccFull": [],
  "OriginalRecipient": "451d9b70cf9364d23ff6f9d51d870251+ticket-42@inbound.haskimail.ru",
  "Subject": "Re: Заказ №42",
  "MessageID": "22c74902-a0c1-4511-804f-341342852c90",
  "ReplyTo": "",
  "MailboxHash": "ticket-42",
  "Date": "Mon, 29 Sep 2026 14:05:13 +0300",
  "TextBody": "Спасибо, всё получил!\n\n29 сентября 2026 г., в 12:00, Магазин написал:\n> Ваш заказ отправлен",
  "HtmlBody": "<p>Спасибо, всё получил!</p>",
  "StrippedTextReply": "Спасибо, всё получил!",
  "Tag": "",
  "Headers": [
    { "Name": "X-Spam-Score", "Value": "0.3" },
    { "Name": "Message-ID", "Value": "<CAE8+abc@mail.example.com>" },
    { "Name": "MIME-Version", "Value": "1.0" }
  ],
  "Attachments": [
    {
      "Name": "check.pdf",
      "Content": "JVBERi0xLjQKJ...",
      "ContentType": "application/pdf",
      "ContentLength": 48213,
      "ContentID": ""
    }
  ]
}

Тестирование с помощью curl #

Отправьте пример JSON на свой обработчик, чтобы проверить его до настройки вебхука. Готовая команда с вашим адресом есть в интерфейсе на вкладке «Инструкции по настройке» входящего канала.

Пример запроса

curl https://example.ru/haski/inbound \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"From": "ivan@example.com", "Subject": "Тест", "TextBody": "Привет", "MailboxHash": "ticket-42", "Attachments": []}'

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

Добавлять ответы клиентов в переписку по заказу или тикету — по MailboxHash и StrippedTextReply.
Создавать задачи и обращения из писем на support@ вашего домена.
Принимать документы и фотографии по почте — из Attachments.
Публиковать комментарии или посты ответом на письмо-уведомление.

Ошибки и повторные попытки #

Письмо считается обработанным (Processed), когда вебхук отвечает кодом 2xx. Ответ ждём до 60 секунд.

При любом другом ответе или ошибке соединения Haskimail повторит отправку 10 раз с растущими интервалами: через 1, 5, 10, 10, 10, 15, 30 минут, 1, 2 и 6 часов — всего около 10,5 часов. Пока идут повторы, у письма статус Scheduled. Если все попытки не удались, письмо получает статус Failed.

Ответ 403 останавливает повторы сразу — используйте его, если письмо не нужно принимать.

Письмо в статусе Failed можно отправить повторно кнопкой «Повторить обработку» в карточке письма или методом retry. Если URL вебхука не задан, письма тоже получают Failed — укажите URL и повторите их.