For AI agents: markdown of this page — /docs-content-en/mail/recipients.md documentation index — /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 Req. 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 app

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 app

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 Invalid or expired key
401 KEY_INACTIVE The key is deactivated
401 KEY_EXPIRED The key has expired

Full list of common API errors — Errors.

See also