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

Mail

Bitrix24 account mail: receiving and sending messages, managing mailboxes, and converting incoming messages into tasks, events, chats, and posts.

Scope: mail · Base URL: https://vibecode.bitrix24.com/v1 · Authorization: X-Api-Key header

Documentation sections

Quick start

Two calls to confirm the API works: get the list of mailboxes and the first messages.

curl

Terminal
# List of mailboxes
curl "https://vibecode.bitrix24.com/v1/mail/mailboxes" \
  -H "X-Api-Key: YOUR_API_KEY"

# Messages in the specified mailbox
curl "https://vibecode.bitrix24.com/v1/mail/messages?mailboxId=5" \
  -H "X-Api-Key: YOUR_API_KEY"

JavaScript

javascript
const BASE = 'https://vibecode.bitrix24.com/v1'
const headers = { 'X-Api-Key': 'YOUR_API_KEY' }

const mbRes = await fetch(`${BASE}/mail/mailboxes`, { headers })
const { data: mailboxes } = await mbRes.json()
const mailboxId = mailboxes[0].id

const msgsRes = await fetch(`${BASE}/mail/messages?mailboxId=${mailboxId}`, { headers })
const { data } = await msgsRes.json()
console.log(`Messages in mailbox: ${data.items.length}`)

Full example

A JavaScript scenario — seven steps: get the list of mailboxes, find the sender address, send a message, read it, reply, and create a task.

javascript
const BASE = 'https://vibecode.bitrix24.com/v1'
const HEADERS = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }

async function api(method, path, body = null) {
  const opts = { method, headers: HEADERS }
  if (body) opts.body = JSON.stringify(body)
  return (await fetch(`${BASE}${path}`, opts)).json()
}

// 1. List of mailboxes → mailboxId
const { data: mailboxes } = await api('GET', '/mail/mailboxes')
const mailboxId = mailboxes[0].id

// 2. Mailbox sender addresses → from string
const { data: sendersData } = await api('GET', `/mail/mailboxes/${mailboxId}/senders`)
const from = sendersData.items[0].sender  // "Name <user@example.com>"

// 3. Send a message
const sendRes = await api('POST', '/mail/messages', {
  from,
  to: ['colleague@example.com'],
  subject: 'Integration request',
  body: 'Hello, please clarify the details.',
})
// → { success: true, data: { success: true, to: ["colleague@example.com"] } }
console.log('Sent:', sendRes.data.to)

// 4. Find the message in the mailbox → id
const { data: msgsData } = await api('GET', `/mail/messages?mailboxId=${mailboxId}&limit=5`)
const messageId = msgsData.items[0].id

// 5. Get the full message text (data.item field)
const { data: msgData } = await api('GET', `/mail/messages/${messageId}`)
console.log('Subject:', msgData.item.subject, '| Body:', msgData.item.body)

// 6. Reply to the message — the message is specified in the path
const replyRes = await api('POST', `/mail/messages/${messageId}/reply`, {
  from,
  to: ['colleague@example.com'],
  subject: `Re: ${msgData.item.subject}`,
  body: 'Thanks, clarification received.',
})
// → { success: true, data: { success: true, to: ["colleague@example.com"] } }
console.log('Reply sent:', replyRes.data.to)

// 7. Create a task from the message
const taskRes = await api('POST', `/mail/messages/${messageId}/task`, {
  title: 'Process the incoming request',
})
// → { success: true, data: { success: true, taskId: 100, messageId: 1000 } }
console.log('Task created, id:', taskRes.data.taskId)

Endpoint reference

Mailboxes:

Method Path Bitrix24 method Description
GET /v1/mail/mailboxes mail.mailbox.list List of mailboxes
GET /v1/mail/mailboxes/:id mail.mailbox.get Get a mailbox
GET /v1/mail/mailboxes/:id/senders mail.mailbox.senders Mailbox sender addresses

Messages:

Method Path Bitrix24 method Description
GET /v1/mail/messages mail.message.list List of messages
GET /v1/mail/messages/:id mail.message.get Get a message
GET /v1/mail/messages/:id/thread mail.message.thread Conversation thread
POST /v1/mail/messages mail.message.send Send a message
POST /v1/mail/messages/:id/reply mail.message.reply Reply to a message
POST /v1/mail/messages/:id/forward mail.message.forward Forward a message
POST /v1/mail/messages/move mail.message.movetofolder Move messages

Creating objects from a message:

Method Path Bitrix24 method Description
POST /v1/mail/messages/:id/task mail.message.createtask Create a task from a message
POST /v1/mail/messages/:id/calendar-event mail.message.createcalendarevent Create an event from a message
POST /v1/mail/messages/:id/chat mail.message.createchat Create a chat from a message
POST /v1/mail/messages/:id/feed-post mail.message.createfeedpost Create a Feed post
POST /v1/mail/messages/:id/crm-activity mail.message.createcrmactivity Bind a message to CRM
DELETE /v1/mail/messages/:id/crm-activity mail.message.removecrmactivity Delete a CRM activity from a message

Recipients:

Method Path Bitrix24 method Description
POST /v1/mail/recipients/contacts mail.recipient.listcontacts Search CRM contacts
POST /v1/mail/recipients/employees mail.recipient.listemployees Search Bitrix24 account employees

Error codes

Mail errors

Code HTTP Description
SCOPE_DENIED 403 The key has no mail scope
TOKEN_MISSING 401 The key has no Bitrix24 tokens configured
INVALID_PARAMS 400 :id or :mailboxId is not a positive integer
INVALID_PARAMS 400 Bitrix24 rejected the request parameters during validation
NOT_FOUND 404 Unknown action (action endpoints only)
ENTITY_NOT_FOUND 404 Message or mailbox not found in Bitrix24
BITRIX_ACCESS_DENIED 403 No permission to access the mailbox or message in Bitrix24
RATE_LIMITED 429 Request limit exceeded (header Retry-After: 2)
BITRIX_UNAVAILABLE 502 Bitrix24 returned a 5xx error
BITRIX_ERROR 422 Other Bitrix24 errors

System errors

Code HTTP Description
MISSING_API_KEY 401 The X-Api-Key header was not provided
INVALID_API_KEY 401 Invalid or expired API key
KEY_INACTIVE 401 The key is deactivated
KEY_EXPIRED 401 The key has expired

Full list of common API errors — Errors.

See also