[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-mail\u002Fmessages\u002Flist":3,"docs-tabs-mail\u002Fmessages\u002Flist":6},{"content":4,"lastmod":5},"\n## Список писем\n\n`GET \u002Fv1\u002Fmail\u002Fmessages`\n\nВозвращает список писем подключённых почтовых ящиков с поддержкой фильтров и постраничной загрузки.\n\n## Параметры\n\n| Параметр | Тип | По умолч. | Описание |\n|----------|-----|-----------|----------|\n| `mailboxId` | number | — | Идентификатор ящика. Список ящиков: `GET \u002Fv1\u002Fmail\u002Fmailboxes` |\n| `searchQuery` | string | — | Полнотекстовый поиск по письмам |\n| `folder` | string | — | Имя папки (например, `INBOX`) |\n| `isSeen` | boolean | — | `true` — только прочитанные, `false` — только непрочитанные |\n| `hasAttachments` | boolean | — | `true` — только письма с вложениями |\n| `dateFrom` | string | — | Начало периода, формат ISO 8601 (`2026-05-01T00:00:00+00:00`) |\n| `dateTo` | string | — | Конец периода, формат ISO 8601 (`2026-05-01T00:00:00+00:00`) |\n| `limit` | number | `50` | Размер страницы, от 1 до 500 |\n| `offset` | number | `0` | Смещение от начала списка |\n\nПри `limit` больше 50 страницы собираются автоматически на стороне сервера, и в ответ добавляется поле `total` — общее число писем, удовлетворяющих фильтру. При `limit` от 1 до 50 возвращается одна страница без поля `total`. Максимум за один запрос — 500 писем.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fmail\u002Fmessages?mailboxId=5&limit=10\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fmail\u002Fmessages?mailboxId=5&limit=10\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch(\n  'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fmail\u002Fmessages?mailboxId=5&limit=10',\n  {\n    headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n  }\n)\nconst { success, data } = await res.json()\nconsole.log(`Писем: ${data.items.length}`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch(\n  'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fmail\u002Fmessages?mailboxId=5&limit=10',\n  {\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n    },\n  }\n)\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `total` | number | Общее число писем, удовлетворяющих фильтру. Возвращается при `limit` больше 50 |\n| `data.items` | array | Массив писем |\n| `data.items[].id` | number | Идентификатор письма |\n| `data.items[].mailboxId` | number | Идентификатор почтового ящика |\n| `data.items[].mailboxEmail` | string | Адрес почтового ящика |\n| `data.items[].subject` | string | Тема письма |\n| `data.items[].from` | string | Отправитель в формате `Имя \u003Cадрес>` |\n| `data.items[].to` | string | Получатель в формате `Имя \u003Cадрес>` |\n| `data.items[].cc` | string \\| null | Адреса в копии, `null` при отсутствии копий |\n| `data.items[].date` | string | Дата отправки в формате `YYYY-MM-DD HH:MM:SS` (без часового пояса) |\n| `data.items[].isSeen` | boolean | Прочитано ли письмо |\n| `data.items[].hasAttachments` | boolean | Есть ли вложения |\n| `data.items[].url` | string | Ссылка на письмо в интерфейсе Битрикс24 |\n| `data.items[].bindings` | array | Привязки письма к объектам Битрикс24. Пустой массив, если письмо ни к чему не привязано |\n| `data.items[].bindings[].type` | string | Тип привязанного объекта (например, `task`) |\n| `data.items[].bindings[].entityId` | number | Идентификатор привязанного объекта |\n| `data.items[].body` | null | Полный текст письма в списке не возвращается (доступен в `GET \u002Fv1\u002Fmail\u002Fmessages\u002F:id`) |\n\nURL любого письма из массива `data.items` — его `id`:\n\n```\nhttps:\u002F\u002F\u003Cportal>.bitrix24.ru\u002Fmail\u002Fmessage\u002F\u003Cid>?source=mail\n```\n\n`\u003Cportal>` — домен портала. Доступ ограничен правами сотрудника в Битрикс24. В ответе также возвращается готовый URL в поле `data.items[].url`.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"items\": [\n      {\n        \"id\": 1763,\n        \"mailboxId\": 5,\n        \"mailboxEmail\": \"support@example.com\",\n        \"subject\": \"Re: Запрос по интеграции\",\n        \"from\": \"Анна Иванова \u003Canna@example.com>\",\n        \"to\": \"Поддержка \u003Csupport@example.com>\",\n        \"cc\": null,\n        \"date\": \"2026-05-18 15:35:32\",\n        \"isSeen\": true,\n        \"hasAttachments\": false,\n        \"url\": \"https:\u002F\u002Fexample.bitrix24.ru\u002Fmail\u002Fmessage\u002F1763\",\n        \"bindings\": [],\n        \"body\": null\n      },\n      {\n        \"id\": 1761,\n        \"mailboxId\": 5,\n        \"mailboxEmail\": \"support@example.com\",\n        \"subject\": \"Запрос по интеграции\",\n        \"from\": \"Поддержка \u003Csupport@example.com>\",\n        \"to\": \"anna@example.com \u003Canna@example.com>\",\n        \"cc\": null,\n        \"date\": \"2026-05-18 15:35:10\",\n        \"isSeen\": true,\n        \"hasAttachments\": false,\n        \"url\": \"https:\u002F\u002Fexample.bitrix24.ru\u002Fmail\u002Fmessage\u002F1761\",\n        \"bindings\": [],\n        \"body\": null\n      }\n    ]\n  }\n}\n```\n\nПри `limit` больше 50 структура ответа та же, дополнительно приходит поле `total` с общим числом писем, удовлетворяющих фильтру.\n\n## Пример ответа при ошибке\n\n403 — нет скоупа `mail`:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'mail' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `mail` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |\n| 429 | `RATE_LIMITED` | Превышен лимит запросов (заголовок `Retry-After: 2`) |\n| 502 | `BITRIX_UNAVAILABLE` | Портал Битрикс24 вернул ошибку 5xx |\n| 422 | `BITRIX_ERROR` | Прочие ошибки Битрикс24 |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный API-ключ |\n| 401 | `KEY_INACTIVE` | API-ключ деактивирован |\n| 401 | `KEY_EXPIRED` | Срок действия API-ключа истёк |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Получить письмо](.\u002Fget.md)\n- [Цепочка переписки](.\u002Fthread.md)\n- [Письма](\u002Fdocs\u002Fmail\u002Fmessages)\n- [Почта](\u002Fdocs\u002Fmail)\n- [Авторизация и ключи](\u002Fdocs\u002Fkeys-auth)\n- [Ошибки](\u002Fdocs\u002Ferrors)\n","2026-07-07",{}]