## 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 messages only, `false` — unread messages only | | `hasAttachments` | boolean | — | `true` — messages with attachments only | | `dateFrom` | string | — | Inclusive start of the period. A `YYYY-MM-DD` date or a full date-time with `Z` or an offset, for example `2026-05-01T00:00:00Z` | | `dateTo` | string | — | Inclusive end of the period. Same formats as `dateFrom` | | `limit` | number | `50` | Page size, from 1 to 500 | The `dateFrom` and `dateTo` parameters accept a `YYYY-MM-DD` date or a full `YYYY-MM-DDTHH:mm:ss` date-time with `Z` or an offset such as `+03:00`, `-03:30`, `+0300`. Fractional seconds may contain 3 or 6 digits, for example `2026-05-01T00:00:00.123Z`. A bare date uses the start of the day for `dateFrom` and the end of the day for `dateTo`. Encode the `+` sign in the query string as `%2B`, for example `dateFrom=2026-05-01T00:00:00%2B03:00`. `URLSearchParams` encodes the sign automatically when building a query. Pages are assembled automatically on the server side up to the requested `limit`. The `total` field is present only when Bitrix24 reports the total number of messages, otherwise it is absent. The `truncated` field tells whether records may exist beyond the returned window. The maximum per request is 500 messages. The method has no offset. To reach messages beyond the window, narrow the selection with the filter parameters — `mailboxId`, `folder`, `dateFrom` and `dateTo`. ## Examples ### curl — personal key ```bash curl "https://vibecode.bitrix24.com/v1/mail/messages?mailboxId=5&limit=10&dateFrom=2026-05-01" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl "https://vibecode.bitrix24.com/v1/mail/messages?mailboxId=5&limit=10&dateFrom=2026-05-01" \ -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&dateFrom=2026-05-01', { 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&dateFrom=2026-05-01', { 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 (optional) | Total number of messages matching the filter. Absent when Bitrix24 does not report the count | | `truncated` | boolean | `true` when more messages may exist beyond the returned window | | `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 built from its `id`: ``` https://.bitrix24.com/mail/message/?source=mail ``` `` is the Bitrix24 portal 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 } ] }, "truncated": false } ``` When Bitrix24 reports the total count, the response also contains the `total` field. If the count is unknown, that field is absent and `truncated` tells whether the list may continue. ## 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` | The key is not recognized — no such key exists on the platform | | 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) - [Keys and authorization](/docs/keys-auth) - [Errors](/docs/errors)