For AI agents: markdown of this page — /docs-content-en/mail/messages/list.md documentation index — /llms.txt

List messages

GET /v1/mail/messages

Returns a list of messages from connected mailboxes with support for filters and pagination.

Parameters

Parameter Type Default Description
mailboxId number — Mailbox identifier. List of mailboxes: GET /v1/mail/mailboxes
searchQuery string — Full-text search across messages
folder string — Folder name (for example, INBOX)
isSeen boolean — true — read only, false — unread only
hasAttachments boolean — true — messages with attachments only
dateFrom string — Start of the period, ISO 8601 format (2026-05-01T00:00:00+00:00)
dateTo string — End of the period, ISO 8601 format (2026-05-01T00:00:00+00:00)
limit number 50 Page size, from 1 to 500
offset number 0 Offset from the start of the list

When limit is greater than 50, pages are assembled automatically on the server side, and the response includes a total field — the overall number of messages matching the filter. When limit is from 1 to 50, a single page is returned without the total field. The maximum per request is 500 messages.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/mail/messages?mailboxId=5&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/mail/messages?mailboxId=5&limit=10" \
  -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/messages?mailboxId=5&limit=10',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data } = await res.json()
console.log(`Messages: ${data.items.length}`)

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/mail/messages?mailboxId=5&limit=10',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
total number Overall number of messages matching the filter. Returned when limit is greater than 50
data.items array Array of messages
data.items[].id number Message identifier
data.items[].mailboxId number Mailbox identifier
data.items[].mailboxEmail string Mailbox address
data.items[].subject string Message subject
data.items[].from string Sender in the Name <address> format
data.items[].to string Recipient in the Name <address> format
data.items[].cc string | null Carbon copy addresses, null when there are none
data.items[].date string Sent date in the YYYY-MM-DD HH:MM:SS format (without timezone)
data.items[].isSeen boolean Whether the message has been read
data.items[].hasAttachments boolean Whether there are attachments
data.items[].url string Link to the message in the Bitrix24 interface
data.items[].bindings array Message bindings to Bitrix24 objects. Empty array if the message is not bound to anything
data.items[].bindings[].type string Type of the bound object (for example, task)
data.items[].bindings[].entityId number Identifier of the bound object
data.items[].body null The full message body is not returned in the list (available in GET /v1/mail/messages/:id)

The URL of any message from the data.items array is its id:

https://<portal>.bitrix24.com/mail/message/<id>?source=mail

<portal> is the Bitrix24 account domain. Access is limited by the employee's permissions in Bitrix24. The response also returns a ready-made URL in the data.items[].url field.

Response example

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1763,
        "mailboxId": 5,
        "mailboxEmail": "support@example.com",
        "subject": "Re: Integration request",
        "from": "Anna Smith <anna@example.com>",
        "to": "Support <support@example.com>",
        "cc": null,
        "date": "2026-05-18 15:35:32",
        "isSeen": true,
        "hasAttachments": false,
        "url": "https://example.bitrix24.com/mail/message/1763",
        "bindings": [],
        "body": null
      },
      {
        "id": 1761,
        "mailboxId": 5,
        "mailboxEmail": "support@example.com",
        "subject": "Integration request",
        "from": "Support <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.com/mail/message/1761",
        "bindings": [],
        "body": null
      }
    ]
  }
}

When limit is greater than 50 the response structure is the same, with an additional total field carrying the overall number of messages matching the filter.

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 The API key does not have the mail scope
401 TOKEN_MISSING The API key has no configured Bitrix24 tokens
429 RATE_LIMITED Request limit exceeded (header Retry-After: 2)
502 BITRIX_UNAVAILABLE The Bitrix24 portal returned a 5xx error
422 BITRIX_ERROR Other Bitrix24 errors
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY Invalid API key
401 KEY_INACTIVE The API key is deactivated
401 KEY_EXPIRED The API key has expired

Full list of common API errors — Errors.

See also