لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/mail/mailboxes.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Mailboxes

List of the mailboxes in your Bitrix24 account and retrieval of details for an individual mailbox and its sender addresses.

Bitrix24 API: mail.mailbox.* Scope: mail

List mailboxes

GET /v1/mail/mailboxes

Returns the list of mailboxes connected to the Bitrix24 account.

Parameters

Parameter In Type Required Default Description
Parameterlimit Inquery Typenumber Requiredno Default50 DescriptionNumber of records per page. The maximum is 5000 — a larger value is clamped to it
Parameteroffset Inquery Typenumber Requiredno Default0 DescriptionOffset from the start of the list

When Bitrix24 does not report the total mailbox count, meta.total is absent. Continue paging by meta.hasMore: a full page means more records may follow, while a short page proves the end of the list.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/mail/mailboxes" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/mail/mailboxes', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { success, data, meta } = await res.json()
console.log(`Mailboxes: ${meta.total}`)

JavaScript — OAuth application

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of mailboxes
Fielddata[].id Typenumber DescriptionMailbox identifier
Fielddata[].name Typestring DescriptionMailbox display name
Fielddata[].email Typestring DescriptionMailbox email address
Fielddata[].senderName Typestring DescriptionSender name placed into the "From" field
Fieldmeta.total Typenumber (optional) DescriptionTotal number of mailboxes on the Bitrix24 account. Absent when Bitrix24 does not report the count
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit

The URL of any mailbox from the data array is built from its id:

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

<portal> is the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Work mail",
      "email": "info@example.com",
      "senderName": "Company"
    },
    {
      "id": 2,
      "name": "Support",
      "email": "support@example.com",
      "senderName": "Support team"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

Error response example

403 — no mail scope:

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

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionAPI key does not have the mail scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded
HTTP409 CodeMAIL_MODULE_NOT_ENABLED DescriptionThe Mail module is absent, the method is not included in the plan, or the account has not yet received the update carrying mail.mailbox.list. Do not blindly retry an unchanged 409; retry after the module is enabled, the plan changes, or the account is updated
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 portal is unavailable
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error

Full list of common API errors — Errors.

Known specifics

  • The list is returned as an array in data with pagination in meta (hasMore and, when known, total); in GET /v1/mail/messages messages are returned differently — in data.items.

See also