Для 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	—	Начало периода включительно. Дата `YYYY-MM-DD` или полная дата-время с `Z` или смещением, например `2026-05-01T00:00:00Z`
`dateTo`	string	—	Конец периода включительно. Те же форматы, что у `dateFrom`
`limit`	number	`50`	Размер страницы, от 1 до 500

Для dateFrom и dateTo принимаются дата YYYY-MM-DD и полная дата-время YYYY-MM-DDTHH:mm:ss с Z или смещением +03:00, -03:30, +0300. Дробная часть секунд может содержать 3 или 6 цифр, например 2026-05-01T00:00:00.123Z. Дата без времени задаёт начало дня для dateFrom и конец дня для dateTo.

Знак + в строке запроса кодируйте как %2B, например dateFrom=2026-05-01T00:00:00%2B03:00. При сборке запроса через URLSearchParams знак кодируется автоматически.

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

Смещения у метода нет. Чтобы дойти до писем за пределами окна, сужайте выборку параметрами отбора — mailboxId, folder, dateFrom и dateTo.

Примеры

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

Terminal

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

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

Terminal

curl "https://vibecode.bitrix24.tech/v1/mail/messages?mailboxId=5&limit=10&dateFrom=2026-05-01" \
  -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&dateFrom=2026-05-01',
  {
    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&dateFrom=2026-05-01',
  {
    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: