Для AI-агентов: markdown этой страницы — /docs-content/mail/messages/list.md индекс документации — /llms.txt

Список писем

GET /v1/mail/messages

Возвращает список писем подключённых почтовых ящиков с поддержкой фильтров и постраничной загрузки.

Параметры

Параметр Тип По умолч. Описание
mailboxId number — Идентификатор ящика. Список ящиков: GET /v1/mail/mailboxes
searchQuery string — Полнотекстовый поиск по письмам
folder string — Имя папки (например, INBOX)
isSeen boolean — true — только прочитанные, false — только непрочитанные
hasAttachments boolean — true — только письма с вложениями
dateFrom string — Начало периода, формат ISO 8601 (2026-05-01T00:00:00+00:00)
dateTo string — Конец периода, формат ISO 8601 (2026-05-01T00:00:00+00:00)
limit number 50 Размер страницы, от 1 до 500
offset number 0 Смещение от начала списка

Страницы собираются автоматически на стороне сервера до заданного limit. Поле total приходит только когда Битрикс24 сообщил общее число писем; иначе оно отсутствует. Поле truncated показывает, могут ли существовать записи за пределами возвращённого окна. Максимум за один запрос — 500 писем.

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/mail/messages?mailboxId=5&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/mail/messages?mailboxId=5&limit=10" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/mail/messages?mailboxId=5&limit=10',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data } = await res.json()
console.log(`Писем: ${data.items.length}`)

JavaScript — OAuth-приложение

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/mail/messages?mailboxId=5&limit=10',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
total number (optional) Общее число писем, удовлетворяющих фильтру. Поле отсутствует, если Битрикс24 не сообщил количество
truncated boolean true, если за пределами возвращённого окна могут существовать другие письма
data.items array Массив писем
data.items[].id number Идентификатор письма
data.items[].mailboxId number Идентификатор почтового ящика
data.items[].mailboxEmail string Адрес почтового ящика
data.items[].subject string Тема письма
data.items[].from string Отправитель в формате Имя <адрес>
data.items[].to string Получатель в формате Имя <адрес>
data.items[].cc string | null Адреса в копии, null при отсутствии копий
data.items[].date string Дата отправки в формате YYYY-MM-DD HH:MM:SS (без часового пояса)
data.items[].isSeen boolean Прочитано ли письмо
data.items[].hasAttachments boolean Есть ли вложения
data.items[].url string Ссылка на письмо в интерфейсе Битрикс24
data.items[].bindings array Привязки письма к объектам Битрикс24. Пустой массив, если письмо ни к чему не привязано
data.items[].bindings[].type string Тип привязанного объекта (например, task)
data.items[].bindings[].entityId number Идентификатор привязанного объекта
data.items[].body null Полный текст письма в списке не возвращается (доступен в GET /v1/mail/messages/:id)

URL любого письма из массива data.items — его id:

https://<portal>.bitrix24.ru/mail/message/<id>?source=mail

<portal> — домен портала. Доступ ограничен правами сотрудника в Битрикс24. В ответе также возвращается готовый URL в поле data.items[].url.

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1763,
        "mailboxId": 5,
        "mailboxEmail": "support@example.com",
        "subject": "Re: Запрос по интеграции",
        "from": "Анна Иванова <anna@example.com>",
        "to": "Поддержка <support@example.com>",
        "cc": null,
        "date": "2026-05-18 15:35:32",
        "isSeen": true,
        "hasAttachments": false,
        "url": "https://example.bitrix24.ru/mail/message/1763",
        "bindings": [],
        "body": null
      },
      {
        "id": 1761,
        "mailboxId": 5,
        "mailboxEmail": "support@example.com",
        "subject": "Запрос по интеграции",
        "from": "Поддержка <support@example.com>",
        "to": "anna@example.com <anna@example.com>",
        "cc": null,
        "date": "2026-05-18 15:35:10",
        "isSeen": true,
        "hasAttachments": false,
        "url": "https://example.bitrix24.ru/mail/message/1761",
        "bindings": [],
        "body": null
      }
    ]
  },
  "truncated": false
}

Когда Битрикс24 сообщает общее количество, структура ответа дополнительно содержит поле total. Если количество неизвестно, поле отсутствует, а truncated показывает, может ли список продолжаться.

Пример ответа при ошибке

403 — нет скоупа mail:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'mail' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа mail
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24
429 RATE_LIMITED Превышен лимит запросов (заголовок Retry-After: 2)
502 BITRIX_UNAVAILABLE Портал Битрикс24 вернул ошибку 5xx
422 BITRIX_ERROR Прочие ошибки Битрикс24
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный API-ключ
401 KEY_INACTIVE API-ключ деактивирован
401 KEY_EXPIRED Срок действия API-ключа истёк

Полный список общих ошибок API — Ошибки.

Смотрите также