Mail messages

Listing, reading and sending messages, working with conversation threads, replies, forwarding and moving between folders.

Bitrix24 API: mail.message.* Scope: mail

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	—	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

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

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 (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 <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 built from its id:

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

<portal> 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 <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
      }
    ]
  },
  "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: