# Почта

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

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

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

- [Почтовые ящики](/docs/mail/mailboxes) — список, получение, отправители (3 эндпоинта)
- [Письма](/docs/mail/messages) — список, чтение, цепочка, отправка, ответ, пересылка, перемещение (7 эндпоинтов)
- [Создание объектов из письма](/docs/mail/conversions) — задача, событие, чат, пост, привязка к CRM и её удаление (6 эндпоинтов)
- [Получатели](/docs/mail/recipients) — поиск контактов и сотрудников (2 эндпоинта)

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

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

### curl

```bash
# Список почтовых ящиков
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. Ответить на письмо — письмо задаётся путём
const replyRes = await api('POST', `/mail/messages/${messageId}/reply`, {
  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`, {
  title: 'Обработать входящий запрос',
})
// → { success: true, data: { success: true, taskId: 100, messageId: 1000 } }
console.log('Задача создана, id:', taskRes.data.taskId)
```

## Справочник эндпоинтов

**Почтовые ящики:**

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|----------------|----------|
| GET | [`/v1/mail/mailboxes`](/docs/mail/mailboxes/list) | mail.mailbox.list | Список почтовых ящиков |
| GET | [`/v1/mail/mailboxes/:id`](/docs/mail/mailboxes/get) | mail.mailbox.get | Получить почтовый ящик |
| GET | [`/v1/mail/mailboxes/:id/senders`](/docs/mail/mailboxes/senders) | mail.mailbox.senders | Адреса отправителя ящика |

**Письма:**

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|----------------|----------|
| GET | [`/v1/mail/messages`](/docs/mail/messages/list) | mail.message.list | Список писем |
| GET | [`/v1/mail/messages/:id`](/docs/mail/messages/get) | mail.message.get | Получить письмо |
| GET | [`/v1/mail/messages/:id/thread`](/docs/mail/messages/thread) | mail.message.thread | Цепочка переписки |
| POST | [`/v1/mail/messages`](/docs/mail/messages/send) | mail.message.send | Отправить письмо |
| POST | [`/v1/mail/messages/:id/reply`](/docs/mail/messages/reply) | mail.message.reply | Ответить на письмо |
| POST | [`/v1/mail/messages/:id/forward`](/docs/mail/messages/forward) | mail.message.forward | Переслать письмо |
| POST | [`/v1/mail/messages/move`](/docs/mail/messages/move) | mail.message.movetofolder | Переместить письма |

**Создание объектов из письма:**

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|----------------|----------|
| POST | [`/v1/mail/messages/:id/task`](/docs/mail/conversions/task) | mail.message.createtask | Создать задачу из письма |
| POST | [`/v1/mail/messages/:id/calendar-event`](/docs/mail/conversions/calendar-event) | mail.message.createcalendarevent | Создать событие из письма |
| POST | [`/v1/mail/messages/:id/chat`](/docs/mail/conversions/chat) | mail.message.createchat | Создать чат из письма |
| POST | [`/v1/mail/messages/:id/feed-post`](/docs/mail/conversions/feed-post) | mail.message.createfeedpost | Создать пост Живой ленты |
| POST | [`/v1/mail/messages/:id/crm-activity`](/docs/mail/conversions/crm-activity-create) | mail.message.createcrmactivity | Привязать письмо к CRM |
| DELETE | [`/v1/mail/messages/:id/crm-activity`](/docs/mail/conversions/crm-activity-delete) | mail.message.removecrmactivity | Удалить дело CRM из письма |

**Получатели:**

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|----------------|----------|
| POST | [`/v1/mail/recipients/contacts`](/docs/mail/recipients/contacts) | mail.recipient.listcontacts | Поиск контактов CRM |
| POST | [`/v1/mail/recipients/employees`](/docs/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 — [Ошибки](/docs/errors).

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

- [Ключи и авторизация](/docs/keys-auth)
- [Конвенции Entity API](/docs/entity-api)
- [Ошибки](/docs/errors)