#Почта

Почта портала Битрикс24: получение и отправка писем, управление ящиками и преобразование входящих сообщений в задачи, события, чаты и посты.

Скоуп: mail · Базовый URL: https://vibecode.bitrix24.tech/v1 · Авторизация: заголовок X-Api-Key

#Разделы документации

#Быстрый старт

Два вызова, чтобы убедиться, что API работает: получить список почтовых ящиков и первые письма.

#curl

Terminal
# Список почтовых ящиков
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

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 — семь шагов: получить список ящиков, узнать адрес для отправки, отправить письмо, прочитать его, ответить и создать задачу.

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 — Ошибки.

#Смотрите также