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
id (path) number yes Message 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
success boolean Always true on success
data.item object Message object
data.item.id number Message identifier
data.item.mailboxId number Mailbox identifier
data.item.mailboxEmail string Mailbox address
data.item.subject string Message subject
data.item.from string Sender in the Name <address> format
data.item.to string Recipient in the Name <address> format
data.item.cc string Carbon copy of the message; an empty string "" when there is no copy
data.item.date string Sent date in the YYYY-MM-DD HH:MM:SS format (without timezone)
data.item.isSeen boolean Whether the message has been read
data.item.hasAttachments boolean Whether there are attachments
data.item.url string Link to the message in the Bitrix24 interface
data.item.bindings array Message bindings to CRM objects
data.item.body string Full 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
400 INVALID_PARAMS id is not a positive integer (message: id must be a positive integer)
404 ENTITY_NOT_FOUND No message found with the given id
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 Invalid API key
401 KEY_INACTIVE The API key is deactivated
401 KEY_EXPIRED The API key has expired

Full list of common API errors — Errors.

See also