Чтение почты

Все запросы выполняются с Bearer-ключом одного ящика и правом messages:read. Чтение через GET не отмечает письмо прочитанным. API изменения, перемещения и удаления пока нет.

`GET /v1/folders`

{
  "items": [
    {"id": "FOLDER_ID", "name": "Входящие", "role": "inbox", "total": 14, "unread": 2}
  ]
}

Идентификаторы непрозрачны. Используйте role, а не переведённое имя папки, чтобы найти входящие.

`GET /v1/messages`

GET /v1/messages?folderId=FOLDER_ID&limit=50

folderId: Идентификатор папки. Без фильтра: письма ящика.
limit: От 1 до 100, по умолчанию 50.
cursor: Значение nextCursor из предыдущего ответа, с URL-кодированием.

{
  "items": [{
    "id": "MESSAGE_ID",
    "folderIds": ["FOLDER_ID"],
    "subject": "Вопрос по заказу",
    "from": [{"address": "client@example.org"}],
    "to": [{"address": "support@example.org"}],
    "receivedAt": "2026-11-04T09:30:00Z",
    "seen": false,
    "flagged": false,
    "size": 2416,
    "hasAttachments": false
  }],
  "nextCursor": "OPAQUE_CURSOR"
}

Как обходить страницы

Выполните первый запрос с нужным фильтром и размером страницы.
Сохраните полученные письма по их id.
Передайте nextCursor в следующем запросе с теми же параметрами.
Продолжайте, пока nextCursor не станет null.

Курсор подписан, действует 15 минут и связан с ключом, ящиком и выборкой. Не разбирайте и не изменяйте его. Не переносите курсор между ключами или фильтрами. Письма идут от новых к старым.

`GET /v1/messages/{id}`

Ответ содержит метаданные, text, html, bodyTruncated и список вложений при наличии права attachments:read. Без этого права attachments будет пустым. Сокращённый пример:

{
  "id": "MESSAGE_ID",
  "subject": "Вопрос по заказу",
  "text": "Здравствуйте! Подскажите статус заказа.",
  "html": "<p>Здравствуйте! Подскажите статус заказа.</p>",
  "bodyTruncated": false,
  "attachments": [
    {"id": "ATTACHMENT_ID", "name": "order.pdf", "type": "application/pdf", "size": 14280}
  ]
}

Каждая текстовая или HTML-часть ограничена 256 КиБ. При bodyTruncated: true тело усечено. HTML письма является недоверенным содержимым: очищайте его перед отображением и не загружайте внешние картинки автоматически.

Вложения и исходное письмо

GET /v1/messages/{id}/attachments/{attachmentId}
GET /v1/messages/{id}/raw

Оба запроса требуют messages:read и attachments:read. Они возвращают файл потоком, не JSON. Максимальный размер потока 64 МиБ. raw содержит исходное MIME-письмо, включая вложения. Доступ к S3 напрямую не выдаётся. Общий бюджет скачиваний: 256 МиБ в час на организацию по размерам запросов; прерванное скачивание может оставаться учтённым.

Кодируйте каждый сегмент идентификатора через encodeURIComponent или аналог вашей платформы. Письмо может быть удалено почтовым приложением между запросами: обрабатывайте 404 без бесконечных повторов.

`GET /v1/events`

История метаданных событий ведётся для ящиков с активными вебхуками. Если вы используете только API чтения и не включали вебхуки, история не собирается. Сам запрос /v1/events не включает наблюдение за ящиком и не восстанавливает прошлые события.

Используйте read-ключ того же ящика. Параметры limit (по умолчанию 50, до 100) и cursor позволяют продолжать чтение истории. Хранятся последние 7 дней; истёкшая позиция возвращает 410, после чего нужно сверить текущее состояние через папки и письма. События передают идентификаторы, без тела письма. Формат и ограничения событий.

Ответ истории: items, nextCursor, hasMore. В отличие от списка писем, nextCursor возвращается и при пустой странице: сохраните его для следующего опроса. При hasMore: true сразу продолжите чтение, иначе сделайте паузу перед следующим запросом.

Ограничения частоты, скачиваний и ошибки API.