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

Get message

GET /v1/mail/messages/:id

Returns a single message by identifier, including the full message body.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionMessage identifier. List: GET /v1/mail/messages

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/mail/messages/1761" \
  -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/1761', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { success, data } = await res.json()
console.log('Subject:', data.item.subject)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/mail/messages/1761', {
  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.item Typeobject DescriptionMessage object
Fielddata.item.id Typenumber DescriptionMessage identifier
Fielddata.item.mailboxId Typenumber DescriptionMailbox identifier
Fielddata.item.mailboxEmail Typestring DescriptionMailbox address
Fielddata.item.subject Typestring DescriptionMessage subject
Fielddata.item.from Typestring DescriptionSender in the Name <address> format
Fielddata.item.to Typestring DescriptionRecipient in the Name <address> format
Fielddata.item.cc Typestring DescriptionCarbon copy addresses; an empty string "" when there are none
Fielddata.item.date Typestring DescriptionSent date in the YYYY-MM-DD HH:MM:SS format (without timezone)
Fielddata.item.isSeen Typeboolean DescriptionWhether the message has been read
Fielddata.item.hasAttachments Typeboolean DescriptionWhether there are attachments
Fielddata.item.url Typestring DescriptionLink to the message in the Bitrix24 interface
Fielddata.item.bindings Typearray DescriptionMessage bindings to CRM objects
Fielddata.item.body Typestring DescriptionFull message body with line breaks (\r\n)

Response example

JSON 
{
  "success": true,
  "data": {
    "item": {
      "id": 1761,
      "mailboxId": 5,
      "mailboxEmail": "support@example.com",
      "subject": "Integration request",
      "from": "Support <support@example.com>",
      "to": "anna@example.com <anna@example.com>",
      "cc": "",
      "date": "2026-05-18 15:35:10",
      "isSeen": true,
      "hasAttachments": false,
      "url": "https://example.bitrix24.com/mail/message/1761",
      "bindings": [],
      "body": "Hello! Please clarify the integration timeline.\r\n\r\n-- \r\nBest regards, support team"
    }
  }
}

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

See also