Как принимать входящие письма

Что такое входящий канал

Входящий канал принимает письма, разбирает их и отправляет на ваш сервер в виде JSON: отправитель, получатели, тема, текст и HTML, заголовки и вложения в base64. У каждого SMTP-сервера есть один входящий канал по умолчанию, его нельзя архивировать.

Откройте SMTP-серверы → ваш сервер → Входящий по умолчанию. У канала четыре вкладки:

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

Входящий адрес и MailboxHash

Все письма на входящий адрес приходят в канал. Адрес показан в Настройках (блок «Входящий адрес»), на вкладке Активность и во втором шаге инструкции.

На него можно пересылать почту со своего ящика или указывать его в Reply-To.

К адресу можно добавить +что-угодно перед @. Значение после плюса (order-123) придёт в поле MailboxHash. Так удобно связывать ответ с заказом, тикетом или пользователем: подставьте ID в Reply-To исходящего письма, и ответ клиента сам укажет, к чему он относится.

Шаг 1. Укажите вебхук

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

1. Создайте в приложении обработчик POST-запросов, который принимает JSON и отвечает кодом 200 (пример — в разделе «Пример обработчика» ниже).

2. Откройте вкладку Настройки → блок Вебхук (или нажмите Открыть настройки в инструкции).

3. Введите адрес в поле URL вебхука, например https://example.ru/haski/inbound.

4. Выберите режим Спам-фильтра (по умолчанию «Выключен»).

5. При необходимости отметьте Исходник письма — тогда полный исходник будет приходить в поле RawEmail.

6. Нажмите Сохранить изменения, затем Проверить вебхук. Вы получите уведомление о его работе.

   

Как обрабатывается ответ сервера:

Спам-фильтр. Если он включён, письма с оценкой спама не ниже порога получают статус «Заблокировано» и на вебхук не уходят. Такие письма можно пропустить вручную на вкладке Активность.

Шаг 2. Отправьте тестовое письмо

1. Скопируйте входящий адрес сервера из второго шага инструкции.

2. Напишите на него из любого почтового ящика.

3. Через несколько секунд письмо появится на вкладке Активность. Если его нет, нажмите Обновить.

На вкладке Активность видна таблица писем: статус, отправитель, тема, MailboxHash и время получения. Над таблицей есть поиск по отправителю, получателю, теме и MailboxHash, а также фильтр Все статусы.

Шаг 3. Подключите свой домен (необязательно)

Свой домен позволяет принимать письма на любой адрес вида support@inbound.example.ru. Лучше использовать отдельный поддомен: MX-запись перенаправит в Haskimail всю почту этого домена.

1. Откройте Настройки → блок Входящий домен.

2. Введите домен в поле Домен, например inbound.example.ru.

3. До сохранения добавьте в DNS домена запись из блока MX-запись:

4. Нажмите Сохранить домен. Haskimail проверит MX-запись. Обновление DNS может занять до нескольких часов.

Пример обработчика и формат JSON

JSON приходит в теле запроса с заголовком Content-Type: application/json. Минимальный обработчик на PHP:

<?php
$email = json_decode(file_get_contents('php://input'), true);

$from    = $email['From'];             // адрес отправителя
$subject = $email['Subject'];
$reply   = $email['StrippedTextReply']; // текст ответа без цитаты
$ticket  = $email['MailboxHash'];       // то, что после «+» в адресе

foreach ($email['Attachments'] ?? [] as $file) {
    file_put_contents('/tmp/' . basename($file['Name']), base64_decode($file['Content']));
}

http_response_code(200); // иначе Haskimail повторит отправку

Проверить обработчик можно запросом с примером JSON (полный пример — на вкладке Инструкции по настройке):

curl https://example.ru/haski/inbound \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "From": "support@haskimail.ru",
    "FromName": "Haskimail",
    "Subject": "Тестовое входящее письмо",
    "MailboxHash": "SampleHash",
    "TextBody": "Это тестовое входящее письмо от Haskimail.",
    "StrippedTextReply": "Это тестовое входящее письмо от Haskimail.",
    "Attachments": []
  }'

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

Правила блокировки

Письма от заблокированных отправителей получают статус «Заблокировано» и не уходят на вебхук. Пока правил нет, на вебхук отправляются все входящие письма, кроме отсеянных спам-фильтром.

1. Откройте вкладку Правила блокировки.

2. Введите в поле email или домен конкретный адрес (spam@example.com) или весь домен (example.com).

3. Нажмите Заблокировать.

Если заблокированное письмо всё же нужно обработать, его можно пропустить вручную на вкладке Активность — в списке оно будет отмечено «мимо правил».