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
limit query number no 50 Number of records per page. The maximum is 5000 — a larger value is truncated to it
offset query number no 0 Offset from the start 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
success boolean Always true on success
data array Array of mailboxes
data[].id number Mailbox identifier
data[].name string Mailbox display name
data[].email string Mailbox email address
data[].senderName string Sender name placed into the "From" field
meta.total number Total number of mailboxes on the Bitrix24 account
meta.hasMore boolean Whether 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 account 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
403 SCOPE_DENIED API key does not have the mail scope
401 TOKEN_MISSING API key has no configured tokens
429 RATE_LIMITED Request limit exceeded
502 BITRIX_UNAVAILABLE The Bitrix24 portal is unavailable
422 BITRIX_ERROR Bitrix24 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 (total, hasMore); in GET /v1/mail/messages messages are returned differently — in data.items.

See also