For AI agents: markdown of this page — /docs-content-en/mail/mailboxes.md documentation index — /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

The response carries no total mailbox count — this list has no meta.total field. 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 on this page: ${data.length}, more: ${meta.hasMore}`)

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.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": {
    "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
HTTP400 CodeUNSUPPORTED_FILTER Descriptionfilter was passed — the mailbox list accepts no filter
HTTP400 CodeINVALID_SORT_FIELD Descriptionsort or order was passed — mailboxes come in a fixed order, sorting is not supported
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 once you have confirmed that the module is enabled, the plan has changed, or the account has been 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); in GET /v1/mail/messages messages are returned differently — in data.items.

See also