Для AI-агентов: markdown этой страницы — /docs-content/entities/crm-emails.md индекс документации — /llms.txt

Письма CRM

Чтение и отправка писем дел CRM. Это отдельный API от модуля почты.

Битрикс24 API: crm.activity.mail.*, crm.{deal,lead,contact,company}.timeline.activity.email.* Скоуп: crm

На портале без соответствующего метода возвращается 422 METHOD_NOT_YET_AVAILABLE, error.release — crm 26.800.1.

Список писем CRM

GET /v1/deals/:id/emails

GET /v1/leads/:id/emails

GET /v1/contacts/:id/emails

GET /v1/companies/:id/emails

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

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типinteger Обяз.да ОписаниеИдентификатор записи из сделок, лидов, контактов или компаний.
Параметрlimit (query) Типinteger Обяз.нет ОписаниеРазмер одной страницы. Эффективное значение приходит в meta.limit.
Параметрoffset (query) Типinteger Обяз.нет ОписаниеСмещение от нуля. Продолжайте с meta.nextOffset.
ПараметрisIncoming (query) Типboolean Обяз.нет Описаниеtrue или 1 — входящие, false или 0 — исходящие. Без параметра — оба направления.

Примеры

curl — личный ключ

Terminal 
curl -X GET "https://vibecode.bitrix24.tech/v1/deals/741/emails" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl -X GET "https://vibecode.bitrix24.tech/v1/deals/741/emails" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/deals/741/emails', {
  method: 'GET',
  headers: {"X-Api-Key": "YOUR_API_KEY"},
})
const result = await response.json()

JavaScript — OAuth-приложение

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/deals/741/emails', {
  method: 'GET',
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN"},
})
const result = await response.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успехе.
Полеdata Типarray ОписаниеПисьма страницы.
Полеdata[].id Типinteger ОписаниеИдентификатор.
Полеdata[].subject Типstring ОписаниеТема письма.
Полеdata[].dateTime Типstring/null ОписаниеДата и время или null.
Полеdata[].isIncoming Типboolean ОписаниеВходящее письмо.
Полеdata[].from Типstring ОписаниеОтправитель.
Полеdata[].to Типstring[] ОписаниеОсновные получатели.
Полеmeta.returnedCount Типinteger ОписаниеЧисло записей в ответе.
Полеmeta.hasMore Типboolean ОписаниеЕсть следующая страница.
Полеmeta.nextOffset Типinteger/null ОписаниеСмещение следующей страницы или null.
Полеmeta.limit Типinteger ОписаниеЭффективный размер страницы.
Полеmeta.offset Типinteger ОписаниеЭффективное смещение.

Пример ответа

Пример структуры с нейтральными данными.

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1203,
      "subject": "Integration request",
      "dateTime": "2026-10-30T10:00:00+00:00",
      "isIncoming": true,
      "from": "sender@example.com",
      "to": [
        "reader@example.com"
      ]
    }
  ],
  "meta": {
    "returnedCount": 1,
    "hasMore": false,
    "nextOffset": null,
    "limit": 50,
    "offset": 0
  }
}

Пример ответа при ошибке

400 — неизвестный параметр:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown query parameter"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеНекорректный тип или идентификатор.
HTTP400 КодUNKNOWN_FILTER_FIELD ОписаниеНеизвестный параметр запроса.
HTTP401 КодTOKEN_MISSING ОписаниеНет доступа к Битрикс24 у ключа.
HTTP403 КодSCOPE_DENIED ОписаниеНужен скоуп crm.
HTTP404 КодENTITY_NOT_FOUND ОписаниеЗапись отсутствует или недоступна.
HTTP404 КодCRM_EMAIL_ACTIVITY_NOT_FOUND ОписаниеДело электронной почты не найдено.
HTTP422 КодMETHOD_NOT_YET_AVAILABLE ОписаниеНа портале нет метода. Требуемый выпуск указан в error.release.
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеОтвет Битрикс24 недоступен или имеет некорректную структуру.

Другие отказы Битрикс24 сохраняют исходные код и текст. Общие ошибки API.

Известные особенности

Это письма дел CRM. Модуль почты работает с другими идентификаторами сообщений.

Один запрос читает одну страницу. Общего количества нет. Продолжайте только по meta.hasMore и meta.nextOffset. Фильтры, сортировка и выбор полей не поддерживаются.

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