Обзор

URL эндпоинта #

API Haskimail построено по принципам REST: каждый ресурс доступен по своему адресу, а действие задается HTTP-методом. Запросы принимаются только по HTTPS.

https://api.haskimail.ru

Тело запроса и ответа — JSON, поэтому передавайте заголовки Accept: application/json и, если у запроса есть тело, Content-Type: application/json. Время в ответах — московское, в формате YYYY-MM-DD HH:MM:SS; даты в параметрах — в формате YYYY-MM-DD.

Аутентификация #

Каждый запрос к API должен содержать API-ключ в HTTP-заголовке. Ключей два вида:

Серверный ключ — X-Haskimail-Server-Token. Нужен для отправки писем и работы с данными сервера: сообщениями, возвратами, шаблонами, каналами, статистикой, вебхуками и стоп-листами. Его можно найти в настройках сервера на вкладке «API-ключи».
Ключ аккаунта — X-Haskimail-Account-Token. Нужен для управления серверами и доменами и для переноса шаблонов между серверами. Его можно найти на вкладке «API-ключи» в настройках аккаунта.

Серверный ключ работает только с данными своего сервера: письмами, возвратами, статистикой, шаблонами, каналами, вебхуками и стоп-листами этого сервера. Чужой объект для него не найден, а методы уровня аккаунта — серверы, домены, перенос шаблонов — отвечают HTTP 401 с кодом 10. Ключ аккаунта работает со всеми серверами аккаунта.

Какой ключ нужен методу, указано в его описании. Если ключ не передан или неверен, API ответит HTTP 401. Если в настройках аккаунта («Безопасность») задан список разрешенных IP-адресов, запросы с других адресов получают HTTP 403.

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

Коды ответов HTTP #

200 — Успех. Запрос выполнен.
401 — Не авторизован. API-ключ не передан, неверен или не подходит к методу.
403 — Доступ запрещен. IP-адрес не входит в список разрешенных для аккаунта.
404 — Не найдено. Неизвестный метод API или объект с таким ID.
413 — Запрос слишком большой. Пакет писем больше 50 МБ.
422 — Ошибка в данных. Запрос не прошел проверку. Тело ответа содержит код и описание ошибки.
500 — Внутренняя ошибка. Запрос не удалось обработать на стороне Haskimail; повторите его позже.
503 — Сервис недоступен. Временная недоступность, например хранилища входящих писем; повторите запрос позже.

Коды ошибок API #

При ошибке тело ответа содержит JSON-объект с кодом и описанием:

{
  "ErrorCode": 1226,
  "Message": "MessageStream doesn't match api key"
}

Поле ErrorCode позволяет программно определить тип ошибки.

Общие

10 — Неверный API-ключ. Ключ не передан, неверен или не подходит к методу: например, тестовый ключ вне отправки, ключ аккаунта для методов входящих писем или серверный ключ для серверов, доменов и переноса шаблонов.
12 — Объект не найден или неполный запрос. Нет объекта с таким ID, не переданы обязательные поля, либо IP-адрес не входит в список разрешенных (тогда HTTP 403).
100 — Внутренняя ошибка. Повторите запрос позже.
404 — Неизвестный метод API.

Отправка писем

3 — Не все обязательные параметры. Например, нет ни HtmlBody, ни TextBody.
4 — Аккаунт не может отправлять. Аккаунт заблокирован, удален или еще на модерации.
6 — Некорректный email-адрес в From, To, Cc или Bcc.
15 — Действие запрещено.
26 — Слишком большое вложение или превышен общий размер вложений.
33 — Недопустимый тип вложения.
35 — Отправка недоступна: недостаточно средств, аккаунт заблокирован за спам или отправка отключена.
36 — Временная ошибка отправки. Повторите запрос позже.
40 — Некорректные заголовки письма в Headers.
52 — Адрес отправителя не подтвержден.
300 — Неверное значение поля в тестовом режиме (HASKIMAIL_API_TEST) либо неверный пакет писем: тело не в том формате, писем нет или их больше 500, письмо пакета — не объект.
400 — Отправитель не подтвержден. Пока аккаунт на модерации, отправлять можно только с подтвержденных адресов и доменов аккаунта.
403 — Неверное поле запроса. Только в тестовом режиме.
411 — Запрещенный тип вложения. Только в тестовом режиме.
412 — Получатель не подтвержден. Пока аккаунт на модерации, отправлять можно только на подтвержденные адреса и домены аккаунта.
1101 — Шаблон не найден.
1226 — Канал не найден, не принадлежит серверу API-ключа или находится в архиве; без MessageStream — у сервера нет активного транзакционного канала.
1236 — Через входящий канал нельзя отправлять письма.

Сообщения и правила для входящих

700 — Неверные параметры запроса сообщений: count, offset, status или дата.
701 — Сообщение не найдено.
702 — Пропустить можно только заблокированное входящее письмо (Blocked).
703 — Повторить можно только входящее письмо с ошибкой (Failed).
800 — Неверные параметры запроса правил или правило не удалось сохранить.
810 — Такое правило уже есть.
812 — Правило не найдено.
813 — Неверное правило: укажите email-адрес или домен.

Домены и шаблоны

510 — Не найден домен или сервер с указанным ID.
512 — Домен уже добавлен в этот или другой аккаунт.
516 — Неверный формат домена.
520 — Перевыпуск DKIM недоступен: перевыпуск уже запущен или домен нельзя перевыпустить, пока он не подтверждён.
1101 — Шаблон не найден.
1120 — Нечего проверять или неверная модель в проверке шаблона: нет ни Subject, ни HtmlBody, ни TextBody, TestRenderModel — не объект «фрагмент → строка», либо указан макет.

Серверы

600 — Некорректный входящий домен.
602 — Входящий домен уже используется или зарезервирован.
606 — Неверный InboundHookUrl: нужен полный URL с http:// или https://.
610 — У входящего домена нет MX-записи со значением inbound.haskimail.ru.
611 — Неверный InboundSpamThreshold: нужно число от 0 до 30 с шагом 5.

Каналы

1221 — Неверный MessageStreamType: создать можно только Transactional или Broadcasts.
1226 — Канал не найден или принадлежит другому серверу (для серверного ключа).
1228 — Входящий канал создать нельзя: он у сервера один и создается автоматически.
1229 — Входящий канал нельзя архивировать.