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
- Mailboxes — list, get, senders (3 endpoints)
- Messages — list, read, thread, send, reply, forward, move (7 endpoints)
- Creating objects from a message — task, event, chat, post, CRM binding (5 endpoints)
- Recipients — search contacts and employees (2 endpoints)
#Quick start
Two calls to confirm the API works: get the list of mailboxes and the first messages.
#curl
# 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
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.
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.