Ответ API при отправке письма и коды ошибок

Методы отправки одного письма POST /email и POST /email/withTemplate всегда возвращают один и тот же набор полей. По HTTP-статусу и полю ErrorCode ваше приложение понимает, принято ли письмо в отправку, а если нет — по какой причине.

Ответы пакетной отправки устроены иначе — они описаны в статье «Пакетная отправка писем через API».

Поля ответа

• To — получатели из запроса.

• SubmittedAt — время приёма письма по Москве в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС.

• MessageID — идентификатор письма. Если получателей несколько, идентификаторы перечислены через запятую в том же порядке. Если письмо не принято — null. По MessageID письмо ищут в API сообщений и в вебхуках.

• ErrorCode — 0, если письмо принято. Иначе — код ошибки.

• Message — описание результата или причина ошибки.

Пример ответа, когда письмо принято (HTTP 200):

{
  "To": "ivan@example.com",
  "SubmittedAt": "2026-10-20 14:30:12",
  "MessageID": "6f1c0b2d9e8a4f7b3c5d2e1a0b9c8d7e",
  "ErrorCode": 0,
  "Message": "OK"
}

Пример ответа, когда письмо не удалось принять (HTTP 422):

{
  "To": "ivan.example.com",
  "SubmittedAt": "2026-10-20 14:30:12",
  "MessageID": null,
  "ErrorCode": 6,
  "Message": "Некорректный email-адрес получателя"
}

Частые коды ошибок

Полный список — в разделе «Коды ошибок API» документации.

Если аккаунт на модерации, ошибка 412 может прийти раньше остальных: пока получатель не подтверждён, письмо без тела или с неверным адресом тоже получит код 412. Подтвердите адреса получателей и отправьте запрос ещё раз — тогда API покажет остальные ошибки, если они есть. Подробнее — в статье «Модерация аккаунта».

Как обрабатывать ответ в приложении

1. Считайте письмо отправленным, только если пришли HTTP 200 и ErrorCode 0. Сохраните MessageID — по нему вы свяжете письмо с событиями доставки, открытиями и кликами.

2. При HTTP 422 запишите в лог ErrorCode и Message: по ним проще найти причину.

3. Повторяйте отправку только при коде 36 и с паузой. Остальные ошибки повтором не исправить: нужно поправить запрос или настройки аккаунта.

4. Убедитесь, что ответ 422 не приводит к падению приложения или к повторной отправке в бесконечном цикле.

Как проверить обработку ошибок

Передайте тестовый ключ HASKIMAIL_API_TEST в заголовке X-Haskimail-Server-Token и отправьте заведомо некорректное письмо, например с адресом без «@». Письма с тестовым ключом никуда не уходят.

curl "https://api.haskimail.ru/email" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Haskimail-Server-Token: HASKIMAIL_API_TEST" \
  -d '{
    "From": "Магазин <shop@example.com>",
    "To": "ivan.example.com",
    "Subject": "Проверка",
    "TextBody": "Тестовое письмо"
  }'

Учтите особенности тестового режима:

• ошибки в данных приходят со своими кодами: 300 — неверное значение поля, 403 — неверное поле запроса, 411 — запрещённый тип вложения;

• проверяется только сам запрос: обязательные поля, адреса и вложения. Канал отправки и другие настройки сервера не проверяются, поэтому ошибку 1226 на тестовом ключе не увидеть.

Чтобы проверить отправку целиком, включая настройки сервера, используйте сервер «Песочница».

Если вы работаете через наши клиентские библиотеки, проверьте, как библиотека сообщает об ответе 422 в вашем коде. Актуальные версии — в статье «Официальные библиотеки Haskimail».