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

Список почтовых ящиков

GET /v1/mail/mailboxes

Возвращает список почтовых ящиков, подключённых к порталу.

Параметры

Параметр В Тип Обяз. По умолч. Описание
Параметрlimit Вquery Типnumber Обяз.нет По умолч.50 ОписаниеКоличество записей на страницу. Максимум — 5000, большее значение усекается до него
Параметрoffset Вquery Типnumber Обяз.нет По умолч.0 ОписаниеСмещение от начала списка

Когда Битрикс24 не сообщает общее количество ящиков, meta.total отсутствует. Продолжайте постраничную загрузку по meta.hasMore: полная страница означает, что записи могут продолжаться, а короткая доказывает конец списка.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/mail/mailboxes" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/mail/mailboxes" \
  -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/mailboxes', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { success, data, meta } = await res.json()
console.log(`Почтовых ящиков: ${meta.total}`)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/mail/mailboxes', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { success, data, meta } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типarray ОписаниеМассив почтовых ящиков
Полеdata[].id Типnumber ОписаниеИдентификатор ящика
Полеdata[].name Типstring ОписаниеОтображаемое имя ящика
Полеdata[].email Типstring ОписаниеАдрес электронной почты ящика
Полеdata[].senderName Типstring ОписаниеИмя отправителя, подставляемое в поле «От»
Полеmeta.total Типnumber (optional) ОписаниеОбщее количество ящиков на портале. Поле отсутствует, если Битрикс24 не сообщил количество
Полеmeta.hasMore Типboolean ОписаниеЕсть ли ещё записи за пределами limit

URL любого ящика из массива data — его id:

https://<portal>.bitrix24.ru/mail/list/<id>/

<portal> — домен портала. Доступ ограничен правами сотрудника в Битрикс24.

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Рабочая почта",
      "email": "info@example.com",
      "senderName": "Компания"
    },
    {
      "id": 2,
      "name": "Поддержка",
      "email": "support@example.com",
      "senderName": "Служба поддержки"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

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

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-ключ не имеет настроенных токенов
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов
HTTP409 КодMAIL_MODULE_NOT_ENABLED ОписаниеНа портале нет модуля «Почта», метод не входит в тариф либо портал ещё не получил обновление с mail.mailbox.list. Не повторяйте неизменный 409 вслепую; повторите запрос после подтверждённого включения модуля, изменения тарифа или обновления портала
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеПортал Битрикс24 недоступен
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 вернул ошибку

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

Известные особенности

  • Список приходит массивом в data с пагинацией в meta (hasMore и, когда количество известно, total); в GET /v1/mail/messages письма возвращаются иначе — в data.items.

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