## 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 ```bash curl "https://vibecode.bitrix24.com/v1/mail/messages?mailboxId=5&limit=10" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash 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
` format | | `data.items[].to` | string | Recipient in the `Name
` 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://.bitrix24.com/mail/message/?source=mail ``` `` 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 ", "to": "Support ", "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 ", "to": "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](/docs/errors). ## See also - [Get message](./get.md) - [Conversation thread](./thread.md) - [Mail messages](/docs/mail/messages) - [Mail](/docs/mail) - [Authorization and keys](/docs/keys-auth) - [Errors](/docs/errors)