لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/mail/recipients.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Recipients

Search CRM contacts and Bitrix24 account employees for use as recipients of outgoing emails.

Bitrix24 API: mail.recipient.* Scope: mail

Search CRM contacts

POST /v1/mail/recipients/contacts

Searches CRM contacts to populate the email recipients field. When the request body is missing or query is empty, returns the most recent contacts.

Request fields (body)

Field Type Required Description
Fieldquery Typestring Requiredno DescriptionSearch string by name or email address. When missing or empty, the most recent contacts are returned

Examples

curl — personal key

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Smith"}' \
  https://vibecode.bitrix24.com/v1/mail/recipients/contacts

curl — OAuth application

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

JavaScript — personal key

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

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/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: 'Smith' }),
  }
)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.items Typearray DescriptionArray of found contacts
Fielddata.items[].id Typenumber DescriptionContact identifier
Fielddata.items[].email Typestring DescriptionEmail address
Fielddata.items[].name Typestring DescriptionContact display name

Response example

JSON 
{
  "success": true,
  "data": {
    "items": [
      { "id": 101, "email": "client@example.com", "name": "Anna Smith" },
      { "id": 102, "email": "sales@example.com", "name": "Sales department" }
    ]
  }
}

Error response example

403 — no mail scope:

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

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the mail scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key is not bound to a Bitrix24 portal
HTTP422 CodeBITRIX_ERROR DescriptionOther Bitrix24 errors
HTTP429 CodeRATE_LIMITED DescriptionRequest rate limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeKEY_INACTIVE DescriptionThe key is deactivated
HTTP401 CodeKEY_EXPIRED DescriptionThe key has expired

Full list of common API errors — Errors.

See also