Аккаунт
Выйти

Обзор

Интеграции

Руководство пользователя

Справочник API

Вебхуки

Обзор

URL эндпоинта #

API Haskimail основан на принципах REST. Аутентифицированные пользователи могут взаимодействовать с любым из наших URI, используя соответствующий метод HTTP-запроса. Мы обеспечиваем шифрование TLS, поэтому все запросы необходимо отправлять по протоколу HTTPS.

https://api.haskimail.ru

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

Для всех запросов к API Haskimail требуется аутентификация. Она выполняется путем отправки корректного API-токена в соответствующем HTTP-заголовке. Haskimail использует два типа API-ключей:

  • Серверный ключ — X-Haskimail-Server-Token Используется для запросов, требующих прав на уровне сервера. Его можно найти на вкладке "API-токены" в настройках вашего сервера Haskimail. Этот токен доступен Владельцам и Администраторам аккаунта, а также пользователям с правами администратора на уровне сервера. 
  • API-ключ аккаунта — X-Haskimail-Account-Token Используется для запросов, требующих прав на уровне аккаунта. Его можно найти на вкладке «API-ключи» в настройках вашего аккаунта Haskimail. Этот токен доступен Владельцу и Администраторам аккаунта.

В документации для каждого эндпоинта API всегда указано, какой заголовок аутентификации следует использовать. Имя и значение заголовка нечувствительны к регистру. Если вы отправите запрос с неверным или отсутствующим заголовком, вы получите ответ HTTP 401 (Unauthorized).

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

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

  • 200 — Успех Запрос выполнен успешно.
  • 401 — Не авторизован Отсутствует или указан неверный API-ключ в заголовке.
  • 404 — Ресурс не найден Вы запросили ресурс, который не существует. Убедитесь в правильности конечной точки и идентификатора.
  • 413 — Слишком большой объем данных Размер запроса превысил установленный в Haskimail лимит: 10 МБ для Email API и 50 МБ для API пакетной отправки писем.
  • 415 — Неподдерживаемый тип данных В API-запросе отсутствуют необходимые заголовки. Сверьтесь с документацией по эндпоинту API, чтобы убедиться, что вы передаете все требуемые заголовки.
  • 422 — Необрабатываемая сущность Ошибка в данных запроса. Это может быть некорректно сформированный JSON или неверные поля. В этом случае тело ответа содержит JSON вида {"ErrorCode": 405, "Message": "детали"} с кодом и сообщением об ошибке
  • 429 — Превышен лимит запросов Вы отправляете запросы слишком часто. Уменьшите частоту обращений к API.
  • 500 — Внутренняя ошибка сервера Проблема с обработкой вашего запроса на серверах Haskimail. В большинстве случаев сообщение в процессе обработки теряется. Мы получаем уведомление о таких ошибках и расследуем их.
  • 503 — Сервис недоступен Во время плановых технических работ сервисы API Haskimail будут возвращать этот HTTP-ответ и соответствующее тело ответа в формате JSON.

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

При обнаружении ошибки в данных запроса сервер Haskimail возвращает HTTP-статус 422. Тело ответа при этом содержит JSON-объект с деталями ошибки:

{
  "ErrorCode": 405,
  "Message": "details"
}

Поле ErrorCode позволяет программно определить тип ошибки. Ниже приведен список поддерживаемых кодов ошибок:

  • 10 — Неверный или отсутствующий API-токен: В заголовке вашего запроса отсутствует или указан неверный API-токен. Обратитесь к документации для конкретного запроса, чтобы узнать, какой API-токен требуется, или прочтите подробнее об аутентификации в Haskimail.
  • 11 — Произошло несколько ошибок: Произошло несколько ошибок. Проверьте свойство Errors в ответе для получения более подробной информации.
  • 12 — Ресурс не найден: Элемент, к которому вы пытаетесь получить доступ, не найден.
  • 13 — Неверный ключ пагинации: Ключ пагинации, указанный в запросе, недействителен.
  • 100 — Технические работы: API Haskimail отключен на время технического обслуживания.
  • 300 — Неверный запрос на отправку письма: Предоставленные вами JSON-данные для запроса не прошли валидацию.
  • 400 — Подпись отправителя не найдена: Вы пытаетесь отправить письмо с адреса отправителя, для которого не настроена подпись. Обратитесь к списку существующих подписей отправителей или добавьте новую.
  • 401 — Подпись отправителя не подтверждена: Вы пытаетесь отправить письмо с адреса, подпись которого не была подтверждена. Вы можете повторно отправить письмо для подтверждения на странице «Подписи отправителей».
  • 402 — Неверный JSON: Предоставленные вами JSON-данные содержат синтаксические ошибки. Рекомендуем проверить ваш JSON с помощью валидатора перед повторной отправкой запроса.
  • 403 — Неверное(ые) поле(я) запроса - {FIELD_NAME}: Предоставленные JSON-данные содержат ошибку. {FIELD_NAME} указывает на неверное поле. Обратитесь к документации для этого запроса, чтобы увидеть список обязательных параметров.
  • 405 — Отправка не разрешена: На вашем аккаунте закончились кредиты. Вы можете приобрести их на странице «Кредиты».
  • 406 — Неактивный получатель: Вы попытались отправить письмо получателю, который помечен как неактивный. Неактивные получатели — это те, от которых был получен жесткий возврат (hard bounce) или жалоба на спам. Повторно активировать можно только получателей с жестким возвратом, найдя их на странице «Активность» вашего сервера и нажав кнопку «Активировать».
  • 409 — Требуется JSON: В вашем HTTP-запросе заголовки Accept и Content-Type не установлены в application/json.
  • 410 — Слишком много сообщений в пакете: Ваш пакетный запрос содержит более 500 сообщений.
  • 411 — Запрещенный тип вложения: Тип файла вложения не разрешен. Ознакомьтесь с нашим списком запрещенных типов файлов.
  • 412 — Аккаунт ожидает подтверждения: Аккаунт, связанный с запросом на отправку, все еще ожидает подтверждения. Пока аккаунт не подтвержден, получатели писем должны иметь тот же домен, что и в адресе отправителя.
  • 413 — Аккаунт не может отправлять: Аккаунт, связанный с запросом, не одобрен для отправки.
  • 500 — Ошибка запроса подписей отправителей: Вы указали неверные параметры в строке запроса. Обратитесь к документации API по подписям отправителей за списком допустимых параметров.
  • 501 — Подпись отправителя не найдена по ID: Мы не смогли найти подпись отправителя по переданному ID.
  • 502 — Не получены данные для обновления подписи: Вы не передали никаких допустимых данных для обновления подписи отправителя.
  • 503 — Нельзя использовать публичный домен: Вы попытались создать подпись отправителя с публичным доменом, что не разрешено.
  • 504 — Такая подпись отправителя уже существует: Вы попытались создать подпись, которая уже существует в Haskimail.
  • 505 — Обновление DKIM уже запланировано: DKIM, который вы пытаетесь обновить, уже находится в очереди на обновление.
  • 506 — Эта подпись отправителя уже подтверждена: Подпись, для которой вы пытались повторно отправить подтверждение, уже была подтверждена.
  • 507 — Вы не являетесь владельцем этой подписи: Эта подпись отправителя не может быть найдена с вашими учетными данными.
  • 510 — Домен не найден: Мы не смогли найти домен, которым вы пытаетесь управлять, по переданному ID.
  • 511 — Переданы неверные поля: Вы не передали никаких допустимых данных для домена.
  • 512 — Такой домен уже существует: Вы попытались создать домен, который уже существует в вашем аккаунте.
  • 513 — Вы не являетесь владельцем этого домена: Этот домен не может быть найден с вашими учетными данными.
  • 514 — "Name" — обязательное поле для создания домена: Вы должны указать параметр Name, чтобы создать домен.
  • 515 — Поле "Name" должно содержать не более 255 символов: Указанное вами имя для домена слишком длинное.
  • 516 — Неверный формат имени: Указанное вами имя для домена имеет неверный формат.
  • 520 — Отсутствует обязательное поле для создания подписи отправителя: При создании подписи вы должны указать значения для Name и FromEmail.
  • 521 — Поле в запросе подписи отправителя слишком длинное: Проверьте свойство Message в ответе для деталей. ConfirmationPersonalNote имеет максимальную длину 400 символов.
  • 522 — Неверное значение поля: Значение может быть неверным email-адресом или доменом. Проверьте свойство Message в ответе для деталей. ConfirmationPersonalNote должно содержать хотя бы один непробельный символ.
  • 600 — Ошибка запроса серверов: Вы указали неверные параметры в строке запроса. Обратитесь к документации API по серверам за списком допустимых параметров.
  • 602 — Дублирующийся домен для входящих: Указанный вами домен для входящих писем уже используется в Haskimail.
  • 603 — Такое имя сервера уже существует: Вы попытались создать сервер с именем, которое уже есть в вашем списке.
  • 604 — У вас нет доступа к удалению: У вас нет разрешения на удаление серверов через API. Пожалуйста, свяжитесь с поддержкой, если вам нужна эта функция.
  • 605 — Невозможно удалить сервер: Мы не смогли удалить этот сервер. Пожалуйста, свяжитесь с поддержкой.
  • 606 — Неверный URL вебхука: URL вебхука, который вы пытаетесь использовать, недействителен или содержит внутренний IP-адрес.
  • 607 — Неверный цвет сервера: Указанный цвет сервера не поддерживается. Пожалуйста, выберите один из следующих цветов: Purple, Blue, Turqoise, Green, Red, Orange, Yellow или Grey.
  • 608 — Имя сервера отсутствует или неверно: Предоставленное вами имя сервера отсутствует или недействительно.
  • 609 — Не получены данные для обновления сервера: Вы не передали никаких допустимых данных для обновления сервера.
  • 610 — Неверная MX-запись для входящего домена: У входящего домена отсутствует MX-запись со значением inbound.haskimail.com.
  • 611 — Неверное значение InboundSpamThreshold: Пожалуйста, используйте число от 0 до 30 с шагом 5.
  • 700 — Ошибка запроса сообщений: Вы указали неверные параметры в строке запроса. Обратитесь к документации API по сообщениям за списком допустимых параметров.
  • 701 — Сообщение не существует: Это сообщение не существует.
  • 702 — Не удалось обойти блокировку этого входящего сообщения, свяжитесь с поддержкой: Возникла проблема при обработке запроса на обход блокировки.
  • 703 — Не удалось повторно отправить это неудавшееся входящее сообщение, свяжитесь с поддержкой: Возникла проблема при обработке запроса на повторную отправку.
  • 800 — Ошибка запроса триггеров: Вы указали неверные параметры в строке запроса.
  • 809 — Не получены данные для триггера: Вы не предоставили параметры в теле JSON-запроса.
  • 810 — Такое правило для входящих уже существует: Вы попытались добавить правило, которое уже существует для этого сервера.
  • 811 — Невозможно удалить это правило, свяжитесь с поддержкой: Мы не смогли удалить это правило с вашего сервера.
  • 812 — Это правило для входящих не найдено: Правило, которым вы пытаетесь управлять, не существует для этого сервера.
  • 813 — Неверный email-адрес или домен: Пожалуйста, используйте действительный email-адрес или домен для настройки правила для входящих.
  • 900 — Ошибка запроса статистики: Вы указали неверные параметры в строке запроса. Обратитесь к документации API по статистике за списком допустимых параметров.
  • 1000 — Ошибка запроса возвратов: Вы указали неверные параметры в строке запроса. Обратитесь к документации API по возвратам за списком допустимых параметров.
  • 1001 — Возврат не найден: BounceID или MessageID, по которому вы ищете, недействителен.
  • 1002 — Требуется параметр BounceID: Вы должны указать BounceID, чтобы получить дамп данных о возврате.
  • 1003 — Невозможно активировать возврат: Определенные типы возвратов и жалоб на спам не могут быть активированы пользователем.
  • 1100 — Ошибка запроса шаблонов: Значение GET-параметра для запроса недействительно.
  • 1101 — Шаблон не найден: TemplateId, LayoutTemplate или Alias ссылаются на шаблон, который не существует или не связан с указанным сервером.
  • 1105 — Будет превышен лимит шаблонов: Сервер может иметь до 100 шаблонов. Обработка этого запроса приведет к превышению лимита.
  • 1109 — Не получены данные для шаблона: Вы не предоставили параметры в теле JSON-запроса. Обратитесь к документации API по шаблонам для получения подробной информации.
  • 1120 — Отсутствует обязательное поле шаблона: В теле POST-запроса отсутствует обязательное поле.
  • 1121 — Поле шаблона слишком большое: Одно из значений в теле запроса превышает наши ограничения по размеру для этого поля.
  • 1122 — Передано неверное поле шаблона: Одно из полей в теле запроса недействительно.
  • 1123 — Включено недопустимое поле: В теле запроса включено поле, которое будет проигнорировано или неприменимо к данной конечной точке.
  • 1125 — Типы шаблонов на исходном и целевом серверах не совпадают: Алиас шаблона на одном сервере является макетом, а на другом — стандартным шаблоном. Шаблоны не могут иметь один и тот же алиас.
  • 1130 — Шаблон макета не может быть удален, так как от него зависят другие шаблоны: Макет не может быть удален, если есть связанные шаблоны, использующие его.
  • 1131 — Заполнитель контента (placeholder) должен присутствовать в HTML и/или текстовом теле макета ровно один раз: Для каждого макета требуется один заполнитель контента. Он не может присутствовать в стандартном шаблоне.
  • 1221 — Неверный 'MessageStreamType': Убедитесь, что вы обращаетесь к каналу, который поддерживает нужную вам функцию (например, не пытаетесь отправить письмо через входящий канал).
  • 1222 — Должен быть предоставлен действительный 'ID': Haskimail не смог найти канал с предоставленным ID, который использовался с данным API-токеном.
  • 1223 — Должно быть предоставлено действительное 'Name': Имя канала не может быть пустым или состоять из пробелов.
  • 1224 — 'Name' слишком длинное, лимит 100 символов: Пожалуйста, создайте более короткое имя.
  • 1225 — Вы достигли максимального количества каналов для этого сервера: Сервер может иметь до 10 каналов.
  • 1226 — Канал для предоставленного 'ID' не найден: Haskimail не смог найти канал с предоставленным ID.
  • 1227 — 'ID' должен быть непустой строкой, начинающейся с латинской буквы: Допустимы строчные латинские буквы, цифры, и символы -, _. Длина ограничена 30 символами.
  • 1228 — На сервере может быть только один входящий канал: Если требуется больше, создайте новый сервер.
  • 1229 — Вы не можете архивировать стандартные транзакционный и входящий каналы: Стандартные каналы Transaction и Inbound не могут быть удалены.
  • 1230 — Предоставленный 'ID' уже существует для этого сервера: ID должны быть уникальными.
  • 1231 — 'Description' слишком длинное, лимит 1000 символов: Пожалуйста, создайте более короткое описание.
  • 1232 — Вы больше не можете разархивировать этот канал: Канал либо удален, либо больше не находится в архиве.
  • 1233 — 'ID' не должен начинаться с префикса 'hm-': Невозможно создать каналы, начинающиеся с hm-.
  • 1234 — 'Description' не должно содержать HTML-теги: Символы < и > не допускаются.
  • 1235 — Указанный 'MessageStream' не существует на этом сервере: Haskimail не смог найти канал с указанным именем.
  • 1236 — Отправка не поддерживается для указанного 'MessageStream': Отправка невозможна через входящие каналы.
  • 1237 — Этот 'ID' зарезервирован: ID all зарезервирован, пожалуйста, используйте другой.
  • 1300 — Неверный запрос на удаление данных: Обратитесь к документации API по удалению данных.
  • 1301 — Неверный ID: Отсутствует или указан неверный ID запроса на удаление данных.
  • 1302 — У вас нет доступа к запросам на удаление данных: У вас нет разрешения на обработку или просмотр запросов на удаление данных через API.