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

Conversation thread

GET /v1/mail/messages/:id/thread

Returns all messages of the conversation thread the specified message belongs to.

The generic filter parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds Warning: 299 - "filter is not supported on this endpoint and was ignored", and records unsupported-filter use in the server log.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionIdentifier of any message from the thread. List: GET /v1/mail/messages

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/mail/messages/1763/thread" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/mail/messages/1763/thread',
  {
    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
Fielddata Typearray DescriptionArray of thread messages, sorted by date
Fielddata[].id Typenumber DescriptionMessage identifier
Fielddata[].subject Typestring DescriptionMessage subject
Fielddata[].from Typestring DescriptionSender in the Name <address> format
Fielddata[].to Typestring DescriptionRecipient in the Name <address> format
Fielddata[].cc Typestring DescriptionCarbon copy of the message; an empty string "" when there is no copy
Fielddata[].date Typestring DescriptionSent date in the YYYY-MM-DD HH:MM:SS format (without timezone)
Fielddata[].body Typestring DescriptionFull message body with line breaks (\r\n)

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1761,
      "subject": "Integration request",
      "from": "Support <support@example.com>",
      "to": "anna@example.com <anna@example.com>",
      "cc": "",
      "date": "2026-05-18 15:35:10",
      "body": "Hello! Please clarify the integration timeline.\r\n\r\n-- \r\nBest regards, support team"
    },
    {
      "id": 1763,
      "subject": "Re: Integration request",
      "from": "Anna Smith <anna@example.com>",
      "to": "Support <support@example.com>",
      "cc": "",
      "date": "2026-05-18 15:35:32",
      "body": "The timeline works. Thank you!"
    }
  ]
}

Error response example

404 — message not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Record with ID = `999999999` not found"
  }
}

Errors

HTTP Code Description
HTTP200 CodeWarning: 299 DescriptionThe filter is ignored by default; previous data is preserved and the warning is sent in the Warning header.
HTTP400 (strict mode only) CodeUNSUPPORTED_FILTER DescriptionThe server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data.
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer (message: id must be a positive integer)
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo message found with the given id
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.

Known specifics

The ID of any message in the thread returns the full thread. A request with the id of any message in the thread returns the same complete set of messages.

See also