[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-mail":3,"docs-tabs-mail":6},{"content":4,"lastmod":5},"\n# Почта\n\nПочта портала Битрикс24: получение и отправка писем, управление ящиками и преобразование входящих сообщений в задачи, события, чаты и посты.\n\n**Скоуп:** `mail` · **Базовый URL:** `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1` · **Авторизация:** заголовок `X-Api-Key`\n\n## Разделы документации\n\n- [Почтовые ящики](\u002Fdocs\u002Fmail\u002Fmailboxes) — список, получение, отправители (3 эндпоинта)\n- [Письма](\u002Fdocs\u002Fmail\u002Fmessages) — список, чтение, цепочка, отправка, ответ, пересылка, перемещение (7 эндпоинтов)\n- [Создание объектов из письма](\u002Fdocs\u002Fmail\u002Fconversions) — задача, событие, чат, пост, привязка к CRM (5 эндпоинтов)\n- [Получатели](\u002Fdocs\u002Fmail\u002Frecipients) — поиск контактов и сотрудников (2 эндпоинта)\n\n## Быстрый старт\n\nДва вызова, чтобы убедиться, что API работает: получить список почтовых ящиков и первые письма.\n\n### curl\n\n```bash\n# Список почтовых ящиков\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fmail\u002Fmailboxes\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n\n# Письма указанного ящика\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fmail\u002Fmessages?mailboxId=5\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### JavaScript\n\n```javascript\nconst BASE = 'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1'\nconst headers = { 'X-Api-Key': 'YOUR_API_KEY' }\n\nconst mbRes = await fetch(`${BASE}\u002Fmail\u002Fmailboxes`, { headers })\nconst { data: mailboxes } = await mbRes.json()\nconst mailboxId = mailboxes[0].id\n\nconst msgsRes = await fetch(`${BASE}\u002Fmail\u002Fmessages?mailboxId=${mailboxId}`, { headers })\nconst { data } = await msgsRes.json()\nconsole.log(`Писем в ящике: ${data.items.length}`)\n```\n\n## Полный пример\n\nСценарий на JavaScript — семь шагов: получить список ящиков, узнать адрес для отправки, отправить письмо, прочитать его, ответить и создать задачу.\n\n```javascript\nconst BASE = 'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1'\nconst HEADERS = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' }\n\nasync function api(method, path, body = null) {\n  const opts = { method, headers: HEADERS }\n  if (body) opts.body = JSON.stringify(body)\n  return (await fetch(`${BASE}${path}`, opts)).json()\n}\n\n\u002F\u002F 1. Список почтовых ящиков → mailboxId\nconst { data: mailboxes } = await api('GET', '\u002Fmail\u002Fmailboxes')\nconst mailboxId = mailboxes[0].id\n\n\u002F\u002F 2. Адреса отправителя ящика → строка from\nconst { data: sendersData } = await api('GET', `\u002Fmail\u002Fmailboxes\u002F${mailboxId}\u002Fsenders`)\nconst from = sendersData.items[0].sender  \u002F\u002F \"Имя \u003Cuser@example.com>\"\n\n\u002F\u002F 3. Отправить письмо\nconst sendRes = await api('POST', '\u002Fmail\u002Fmessages', {\n  from,\n  to: ['colleague@example.com'],\n  subject: 'Запрос по интеграции',\n  body: 'Добрый день, прошу уточнить детали.',\n})\n\u002F\u002F → { success: true, data: { success: true, to: [\"colleague@example.com\"] } }\nconsole.log('Отправлено:', sendRes.data.to)\n\n\u002F\u002F 4. Найти письмо в ящике → id\nconst { data: msgsData } = await api('GET', `\u002Fmail\u002Fmessages?mailboxId=${mailboxId}&limit=5`)\nconst messageId = msgsData.items[0].id\n\n\u002F\u002F 5. Получить полный текст письма (поле data.item)\nconst { data: msgData } = await api('GET', `\u002Fmail\u002Fmessages\u002F${messageId}`)\nconsole.log('Тема:', msgData.item.subject, '| Текст:', msgData.item.body)\n\n\u002F\u002F 6. Ответить на письмо (replyToMessageId — обязательное поле)\nconst replyRes = await api('POST', `\u002Fmail\u002Fmessages\u002F${messageId}\u002Freply`, {\n  replyToMessageId: messageId,\n  from,\n  to: ['colleague@example.com'],\n  subject: `Re: ${msgData.item.subject}`,\n  body: 'Спасибо, уточнение принято.',\n})\n\u002F\u002F → { success: true, data: { success: true, to: [\"colleague@example.com\"] } }\nconsole.log('Ответ отправлен:', replyRes.data.to)\n\n\u002F\u002F 7. Создать задачу из письма\nconst taskRes = await api('POST', `\u002Fmail\u002Fmessages\u002F${messageId}\u002Ftask`, {\n  messageId,\n  title: 'Обработать входящий запрос',\n})\n\u002F\u002F → { success: true, data: { success: true, taskId: 100, messageId: 1000 } }\nconsole.log('Задача создана, id:', taskRes.data.taskId)\n```\n\n## Справочник эндпоинтов\n\n**Почтовые ящики:**\n\n| Метод | Путь | Bitrix24 метод | Описание |\n|-------|------|----------------|----------|\n| GET | [`\u002Fv1\u002Fmail\u002Fmailboxes`](\u002Fdocs\u002Fmail\u002Fmailboxes\u002Flist) | mail.mailbox.list | Список почтовых ящиков |\n| GET | [`\u002Fv1\u002Fmail\u002Fmailboxes\u002F:id`](\u002Fdocs\u002Fmail\u002Fmailboxes\u002Fget) | mail.mailbox.get | Получить почтовый ящик |\n| GET | [`\u002Fv1\u002Fmail\u002Fmailboxes\u002F:id\u002Fsenders`](\u002Fdocs\u002Fmail\u002Fmailboxes\u002Fsenders) | mail.mailbox.senders | Адреса отправителя ящика |\n\n**Письма:**\n\n| Метод | Путь | Bitrix24 метод | Описание |\n|-------|------|----------------|----------|\n| GET | [`\u002Fv1\u002Fmail\u002Fmessages`](\u002Fdocs\u002Fmail\u002Fmessages\u002Flist) | mail.message.list | Список писем |\n| GET | [`\u002Fv1\u002Fmail\u002Fmessages\u002F:id`](\u002Fdocs\u002Fmail\u002Fmessages\u002Fget) | mail.message.get | Получить письмо |\n| GET | [`\u002Fv1\u002Fmail\u002Fmessages\u002F:id\u002Fthread`](\u002Fdocs\u002Fmail\u002Fmessages\u002Fthread) | mail.message.thread | Цепочка переписки |\n| POST | [`\u002Fv1\u002Fmail\u002Fmessages`](\u002Fdocs\u002Fmail\u002Fmessages\u002Fsend) | mail.message.send | Отправить письмо |\n| POST | [`\u002Fv1\u002Fmail\u002Fmessages\u002F:id\u002Freply`](\u002Fdocs\u002Fmail\u002Fmessages\u002Freply) | mail.message.reply | Ответить на письмо |\n| POST | [`\u002Fv1\u002Fmail\u002Fmessages\u002F:id\u002Fforward`](\u002Fdocs\u002Fmail\u002Fmessages\u002Fforward) | mail.message.forward | Переслать письмо |\n| POST | [`\u002Fv1\u002Fmail\u002Fmessages\u002Fmove`](\u002Fdocs\u002Fmail\u002Fmessages\u002Fmove) | mail.message.movetofolder | Переместить письма |\n\n**Создание объектов из письма:**\n\n| Метод | Путь | Bitrix24 метод | Описание |\n|-------|------|----------------|----------|\n| POST | [`\u002Fv1\u002Fmail\u002Fmessages\u002F:id\u002Ftask`](\u002Fdocs\u002Fmail\u002Fconversions\u002Ftask) | mail.message.createtask | Создать задачу из письма |\n| POST | [`\u002Fv1\u002Fmail\u002Fmessages\u002F:id\u002Fcalendar-event`](\u002Fdocs\u002Fmail\u002Fconversions\u002Fcalendar-event) | mail.message.createcalendarevent | Создать событие из письма |\n| POST | [`\u002Fv1\u002Fmail\u002Fmessages\u002F:id\u002Fchat`](\u002Fdocs\u002Fmail\u002Fconversions\u002Fchat) | mail.message.createchat | Создать чат из письма |\n| POST | [`\u002Fv1\u002Fmail\u002Fmessages\u002F:id\u002Ffeed-post`](\u002Fdocs\u002Fmail\u002Fconversions\u002Ffeed-post) | mail.message.createfeedpost | Создать пост Живой ленты |\n| POST | [`\u002Fv1\u002Fmail\u002Fmessages\u002F:id\u002Fcrm-activity`](\u002Fdocs\u002Fmail\u002Fconversions\u002Fcrm-activity-create) | mail.message.createcrmactivity | Привязать письмо к CRM |\n\n**Получатели:**\n\n| Метод | Путь | Bitrix24 метод | Описание |\n|-------|------|----------------|----------|\n| POST | [`\u002Fv1\u002Fmail\u002Frecipients\u002Fcontacts`](\u002Fdocs\u002Fmail\u002Frecipients\u002Fcontacts) | mail.recipient.listcontacts | Поиск контактов CRM |\n| POST | [`\u002Fv1\u002Fmail\u002Frecipients\u002Femployees`](\u002Fdocs\u002Fmail\u002Frecipients\u002Femployees) | mail.recipient.listemployees | Поиск сотрудников портала |\n\n## Коды ошибок\n\n### Ошибки почты\n\n| Код | HTTP | Описание |\n|-----|------|----------|\n| `SCOPE_DENIED` | 403 | У ключа нет скоупа `mail` |\n| `TOKEN_MISSING` | 401 | У ключа не настроены токены Битрикс24 |\n| `INVALID_PARAMS` | 400 | `:id` или `:mailboxId` не является положительным целым числом |\n| `INVALID_PARAMS` | 400 | Битрикс24 отклонил валидацию параметров запроса |\n| `NOT_FOUND` | 404 | Неизвестное действие (только для action-эндпоинтов) |\n| `ENTITY_NOT_FOUND` | 404 | Письмо или ящик не найдены в Битрикс24 |\n| `BITRIX_ACCESS_DENIED` | 403 | Нет прав на доступ к ящику или сообщению в Битрикс24 |\n| `RATE_LIMITED` | 429 | Превышен лимит запросов (заголовок `Retry-After: 2`) |\n| `BITRIX_UNAVAILABLE` | 502 | Битрикс24 вернул ошибку 5xx |\n| `BITRIX_ERROR` | 422 | Прочие ошибки Битрикс24 |\n\n### Системные ошибки\n\n| Код | HTTP | Описание |\n|-----|------|----------|\n| `MISSING_API_KEY` | 401 | Не передан заголовок `X-Api-Key` |\n| `INVALID_API_KEY` | 401 | Неверный или просроченный API-ключ |\n| `KEY_INACTIVE` | 401 | Ключ деактивирован |\n| `KEY_EXPIRED` | 401 | Ключ истёк |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Ключи и авторизация](\u002Fdocs\u002Fkeys-auth)\n- [Конвенции Entity API](\u002Fdocs\u002Fentity-api)\n- [Ошибки](\u002Fdocs\u002Ferrors)\n","2026-06-24",{}]