## Список писем `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 — личный ключ ```bash curl "https://vibecode.bitrix24.tech/v1/mail/messages?mailboxId=5&limit=10" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash 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://.bitrix24.ru/mail/message/?source=mail ``` `` — домен портала. Доступ ограничен правами сотрудника в Битрикс24. В ответе также возвращается готовый URL в поле `data.items[].url`. ## Пример ответа ```json { "success": true, "data": { "items": [ { "id": 1763, "mailboxId": 5, "mailboxEmail": "support@example.com", "subject": "Re: Запрос по интеграции", "from": "Анна Иванова ", "to": "Поддержка ", "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": "Поддержка ", "to": "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 — [Ошибки](/docs/errors). ## Смотрите также - [Получить письмо](./get.md) - [Цепочка переписки](./thread.md) - [Письма](/docs/mail/messages) - [Почта](/docs/mail) - [Ключи и авторизация](/docs/keys-auth) - [Ошибки](/docs/errors)