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

Письма

Список, чтение и отправка писем, работа с цепочками переписки, ответы, пересылка и перемещение между папками.

Битрикс24 API: mail.message.* Скоуп: mail

Список писем

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:

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

Ошибки

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

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

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