Dành cho AI agent: markdown của trang này — /docs-content-en/mail/recipients.md chỉ mục tài liệu — /llms.txt

Hiện tại, các bài viết trong tài liệu chỉ có bằng tiếng Anh.

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
query string no Search 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
success boolean true on success
data.items array Array of found contacts
data.items[].id number Contact identifier
data.items[].email string Email address
data.items[].name string Contact 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
403 SCOPE_DENIED The key lacks the mail scope
401 TOKEN_MISSING The key is not bound to a Bitrix24 portal
422 BITRIX_ERROR Other Bitrix24 errors
429 RATE_LIMITED Request rate limit exceeded
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable
401 MISSING_API_KEY The X-Api-Key header was not provided
401 INVALID_API_KEY The key is not recognized — no such key exists on the platform
401 KEY_INACTIVE The key is deactivated
401 KEY_EXPIRED The key has expired

Full list of common API errors — Errors.

See also