#Mail

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

Scope: mail · Base URL: https://vibecode.bitrix24.tech/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.tech/v1/mail/mailboxes" \
  -H "X-Api-Key: YOUR_API_KEY"

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

#JavaScript

javascript
const BASE = 'https://vibecode.bitrix24.tech/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.tech/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 (replyToMessageId — required field)
const replyRes = await api('POST', `/mail/messages/${messageId}/reply`, {
  replyToMessageId: messageId,
  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`, {
  messageId,
  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 an Activity Stream post
POST `/v1/mail/messages/:id/crm-activity` mail.message.createcrmactivity Bind a message to CRM

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 portal 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 request parameter 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