Inbox API

Авторизация

Передавайте API-ключ в каждом запросе: Authorization: Bearer YOUR_API_KEY. Ключ можно создать в разделе API кабинета.

Получить письма

limit необязательный: по умолчанию API возвращает 50 писем, допустимый диапазон — от 1 до 100. Новые письма идут первыми.

curl -sS "https://kratk.ru/api/inbox?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ содержит письма и данные следующей страницы. id возвращается десятичной строкой: храните и передавайте его без преобразования в JavaScript Number.

{
  "items": [
    {
      "id": "42",
      "domain": "example.ru",
      "recipient": "orders@example.ru",
      "sender": "customer@example.com",
      "subject": "Новый заказ",
      "preview": "Текстовое превью письма",
      "receivedAt": "2026-08-06T09:30:00.000Z",
      "readAt": null
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "OPAQUE_CURSOR"
  }
}

Следующая страница

Если hasMore равен true, передайте полученный nextCursor без изменений. Не разбирайте и не создавайте cursor самостоятельно: используйте только значение, возвращённое текущей версией API.

curl -sS "https://kratk.ru/api/inbox?limit=50&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_API_KEY"

Получить одно письмо

curl -sS https://kratk.ru/api/inbox/MESSAGE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ включает текстовую и HTML-версию письма, заголовки, отправителя, получателя и состояние прочтения. HTML возвращается как данные — безопасно обрабатывайте его в своей системе.

Пометить прочитанным или непрочитанным

Передайте {"read":true}, чтобы пометить письмо прочитанным, или {"read":false}, чтобы вернуть состояние «Непрочитано».

curl -sS https://kratk.ru/api/inbox/MESSAGE_ID \
  -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"read":false}'

Удалить письмо

Удаление необратимо. Успешный запрос возвращает 204 No Content без тела ответа.

curl -sS https://kratk.ru/api/inbox/MESSAGE_ID \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

Отправить письмо

Письмо уходит с адреса на вашем домене, для которого настроена отправка (SPF и DKIM, см. Domains и Mail API). Адрес отправителя — ящик домена: создайте его в настройках домена в кабинете. Один получатель, тело — html (очищается на сервере: безопасные теги, ссылки http/https/mailto) или text. Для ответа передайте inReplyTo — messageId исходного письма.

curl -sS https://kratk.ru/api/inbox/send \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domainId": "DOMAIN_ID",
    "localPart": "info",
    "to": "customer@example.com",
    "subject": "Ваш заказ",
    "html": "<p>Спасибо за заказ!</p>"
  }'

Лимит — 30 писем в час и 200 в сутки на аккаунт (429 при превышении). Отправленные: GET /api/inbox/sent (limit, cursor, search) и GET /api/inbox/sent/ID с текстом и HTML письма. Поля: sender, recipient, subject, status (sent или failed), error, createdAt.

Коды ошибок

• 400 — некорректный limit, cursor или тело PATCH
• 401 — API-ключ отсутствует, неверен или недоступен на тарифе
• 404 — письмо не найдено или не принадлежит вашему аккаунту
• 429 — превышен лимит отправки
• 502 — сервер получателя не принял письмо
• 500 — внутренняя ошибка сервиса