لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/mail/messages.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

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
ParametermailboxId Typenumber Default— DescriptionMailbox identifier. List of mailboxes: GET /v1/mail/mailboxes
ParametersearchQuery Typestring Default— DescriptionFull-text search across messages
Parameterfolder Typestring Default— DescriptionFolder name (for example, INBOX)
ParameterisSeen Typeboolean Default— Descriptiontrue — read messages only, false — unread messages only
ParameterhasAttachments Typeboolean Default— Descriptiontrue — messages with attachments only
ParameterdateFrom Typestring Default— DescriptionInclusive 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
ParameterdateTo Typestring Default— DescriptionInclusive end of the period. Same formats as dateFrom
Parameterlimit Typenumber Default50 DescriptionPage 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

Terminal 
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

Terminal 
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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fieldtotal Typenumber (optional) DescriptionTotal number of messages matching the filter. Absent when Bitrix24 does not report the count
Fieldtruncated Typeboolean Descriptiontrue when more messages may exist beyond the returned window
Fielddata.items Typearray DescriptionArray of messages
Fielddata.items[].id Typenumber DescriptionMessage identifier
Fielddata.items[].mailboxId Typenumber DescriptionMailbox identifier
Fielddata.items[].mailboxEmail Typestring DescriptionMailbox address
Fielddata.items[].subject Typestring DescriptionMessage subject
Fielddata.items[].from Typestring DescriptionSender in the Name <address> format
Fielddata.items[].to Typestring DescriptionRecipient in the Name <address> format
Fielddata.items[].cc Typestring | null DescriptionCarbon copy addresses, null when there are none
Fielddata.items[].date Typestring DescriptionSent date in the YYYY-MM-DD HH:MM:SS format (without timezone)
Fielddata.items[].isSeen Typeboolean DescriptionWhether the message has been read
Fielddata.items[].hasAttachments Typeboolean DescriptionWhether there are attachments
Fielddata.items[].url Typestring DescriptionLink to the message in the Bitrix24 interface
Fielddata.items[].bindings Typearray DescriptionMessage bindings to Bitrix24 objects. Empty array if the message is not bound to anything
Fielddata.items[].bindings[].type Typestring DescriptionType of the bound object (for example, task)
Fielddata.items[].bindings[].entityId Typenumber DescriptionIdentifier of the bound object
Fielddata.items[].body Typenull DescriptionThe 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:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'mail' scope"
  }
}

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the mail scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured Bitrix24 tokens
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded (header Retry-After: 2)
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 portal returned a 5xx error
HTTP422 CodeBITRIX_ERROR DescriptionOther Bitrix24 errors
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is deactivated
HTTP401 CodeKEY_EXPIRED DescriptionThe API key has expired

Full list of common API errors — Errors.

See also