Получатели

Поиск контактов CRM и сотрудников портала для использования в качестве получателей исходящих писем.

Битрикс24 API: mail.recipient.* Скоуп: mail

Поиск контактов CRM

POST /v1/mail/recipients/contacts

Ищет контакты CRM для подстановки в поле получателей письма. При отсутствии тела запроса или пустом query возвращает последние контакты.

Поля запроса (body)

Поле Тип Обяз. Описание
query string нет Строка поиска по имени или адресу электронной почты. При отсутствии или пустом значении возвращаются последние контакты

Примеры

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

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Иванова"}' \
  https://vibecode.bitrix24.tech/v1/mail/recipients/contacts

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

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Иванова"}' \
  https://vibecode.bitrix24.tech/v1/mail/recipients/contacts

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/mail/recipients/contacts',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query: 'Иванова' }),
  }
)
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log(body.data.items)

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/mail/recipients/contacts',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query: 'Иванова' }),
  }
)

Поля ответа

Поле Тип Описание
success boolean true при успешном выполнении
data.items array Массив найденных контактов
data.items[].id number Идентификатор контакта
data.items[].email string Адрес электронной почты
data.items[].name string Отображаемое имя контакта

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

JSON 
{
  "success": true,
  "data": {
    "items": [
      { "id": 101, "email": "client@example.com", "name": "Анна Иванова" },
      { "id": 102, "email": "sales@example.com", "name": "Отдел продаж" }
    ]
  }
}

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

403 — нет скоупа mail:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'mail' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED Ключу не хватает скоупа mail
401 TOKEN_MISSING Ключ не привязан к порталу Битрикс24
422 BITRIX_ERROR Битрикс24 отклонил запрос — ошибка при валидации объекта запроса
429 RATE_LIMITED Превышен лимит запросов
502 BITRIX_UNAVAILABLE Битрикс24 недоступен
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный ключ
401 KEY_INACTIVE Ключ деактивирован
401 KEY_EXPIRED Срок действия ключа истёк

Полный список общих ошибок API — Ошибки.

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