#Почта
Почта портала Битрикс24: получение и отправка писем, управление ящиками и преобразование входящих сообщений в задачи, события, чаты и посты.
Скоуп: mail · Базовый URL: https://vibecode.bitrix24.tech/v1 · Авторизация: заголовок X-Api-Key
#Разделы документации
- Почтовые ящики — список, получение, отправители (3 эндпоинта)
- Письма — список, чтение, цепочка, отправка, ответ, пересылка, перемещение (7 эндпоинтов)
- Создание объектов из письма — задача, событие, чат, пост, привязка к CRM (5 эндпоинтов)
- Получатели — поиск контактов и сотрудников (2 эндпоинта)
#Быстрый старт
Два вызова, чтобы убедиться, что API работает: получить список почтовых ящиков и первые письма.
#curl
# Список почтовых ящиков
curl "https://vibecode.bitrix24.tech/v1/mail/mailboxes" \
-H "X-Api-Key: YOUR_API_KEY"
# Письма указанного ящика
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(`Писем в ящике: ${data.items.length}`)
#Полный пример
Сценарий на 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. Список почтовых ящиков → mailboxId
const { data: mailboxes } = await api('GET', '/mail/mailboxes')
const mailboxId = mailboxes[0].id
// 2. Адреса отправителя ящика → строка from
const { data: sendersData } = await api('GET', `/mail/mailboxes/${mailboxId}/senders`)
const from = sendersData.items[0].sender // "Имя <user@example.com>"
// 3. Отправить письмо
const sendRes = await api('POST', '/mail/messages', {
from,
to: ['colleague@example.com'],
subject: 'Запрос по интеграции',
body: 'Добрый день, прошу уточнить детали.',
})
// → { success: true, data: { success: true, to: ["colleague@example.com"] } }
console.log('Отправлено:', sendRes.data.to)
// 4. Найти письмо в ящике → id
const { data: msgsData } = await api('GET', `/mail/messages?mailboxId=${mailboxId}&limit=5`)
const messageId = msgsData.items[0].id
// 5. Получить полный текст письма (поле data.item)
const { data: msgData } = await api('GET', `/mail/messages/${messageId}`)
console.log('Тема:', msgData.item.subject, '| Текст:', msgData.item.body)
// 6. Ответить на письмо (replyToMessageId — обязательное поле)
const replyRes = await api('POST', `/mail/messages/${messageId}/reply`, {
replyToMessageId: messageId,
from,
to: ['colleague@example.com'],
subject: `Re: ${msgData.item.subject}`,
body: 'Спасибо, уточнение принято.',
})
// → { success: true, data: { success: true, to: ["colleague@example.com"] } }
console.log('Ответ отправлен:', replyRes.data.to)
// 7. Создать задачу из письма
const taskRes = await api('POST', `/mail/messages/${messageId}/task`, {
messageId,
title: 'Обработать входящий запрос',
})
// → { success: true, data: { success: true, taskId: 100, messageId: 1000 } }
console.log('Задача создана, id:', taskRes.data.taskId)
#Справочник эндпоинтов
Почтовые ящики:
| Метод | Путь | Bitrix24 метод | Описание |
|---|---|---|---|
| GET | `/v1/mail/mailboxes` | mail.mailbox.list | Список почтовых ящиков |
| GET | `/v1/mail/mailboxes/:id` | mail.mailbox.get | Получить почтовый ящик |
| GET | `/v1/mail/mailboxes/:id/senders` | mail.mailbox.senders | Адреса отправителя ящика |
Письма:
| Метод | Путь | Bitrix24 метод | Описание |
|---|---|---|---|
| GET | `/v1/mail/messages` | mail.message.list | Список писем |
| GET | `/v1/mail/messages/:id` | mail.message.get | Получить письмо |
| GET | `/v1/mail/messages/:id/thread` | mail.message.thread | Цепочка переписки |
| POST | `/v1/mail/messages` | mail.message.send | Отправить письмо |
| POST | `/v1/mail/messages/:id/reply` | mail.message.reply | Ответить на письмо |
| POST | `/v1/mail/messages/:id/forward` | mail.message.forward | Переслать письмо |
| POST | `/v1/mail/messages/move` | mail.message.movetofolder | Переместить письма |
Создание объектов из письма:
| Метод | Путь | Bitrix24 метод | Описание |
|---|---|---|---|
| POST | `/v1/mail/messages/:id/task` | mail.message.createtask | Создать задачу из письма |
| POST | `/v1/mail/messages/:id/calendar-event` | mail.message.createcalendarevent | Создать событие из письма |
| POST | `/v1/mail/messages/:id/chat` | mail.message.createchat | Создать чат из письма |
| POST | `/v1/mail/messages/:id/feed-post` | mail.message.createfeedpost | Создать пост Живой ленты |
| POST | `/v1/mail/messages/:id/crm-activity` | mail.message.createcrmactivity | Привязать письмо к CRM |
Получатели:
| Метод | Путь | Bitrix24 метод | Описание |
|---|---|---|---|
| POST | `/v1/mail/recipients/contacts` | mail.recipient.listcontacts | Поиск контактов CRM |
| POST | `/v1/mail/recipients/employees` | mail.recipient.listemployees | Поиск сотрудников портала |
#Коды ошибок
#Ошибки почты
| Код | HTTP | Описание |
|---|---|---|
SCOPE_DENIED |
403 | У ключа нет скоупа mail |
TOKEN_MISSING |
401 | У ключа не настроены токены Битрикс24 |
INVALID_PARAMS |
400 | :id или :mailboxId не является положительным целым числом |
INVALID_PARAMS |
400 | Битрикс24 отклонил валидацию параметров запроса |
NOT_FOUND |
404 | Неизвестное действие (только для action-эндпоинтов) |
ENTITY_NOT_FOUND |
404 | Письмо или ящик не найдены в Битрикс24 |
BITRIX_ACCESS_DENIED |
403 | Нет прав на доступ к ящику или сообщению в Битрикс24 |
RATE_LIMITED |
429 | Превышен лимит запросов (заголовок Retry-After: 2) |
BITRIX_UNAVAILABLE |
502 | Битрикс24 вернул ошибку 5xx |
BITRIX_ERROR |
422 | Прочие ошибки Битрикс24 |
#Системные ошибки
| Код | HTTP | Описание |
|---|---|---|
MISSING_API_KEY |
401 | Не передан заголовок X-Api-Key |
INVALID_API_KEY |
401 | Неверный или просроченный API-ключ |
KEY_INACTIVE |
401 | Ключ деактивирован |
KEY_EXPIRED |
401 | Ключ истёк |
Полный список общих ошибок API — Ошибки.