For AI agents: markdown of this page — /docs-content-en/entities/crm-emails.md documentation index — /llms.txt

CRM e-mails

Read and send CRM activity e-mails. This API is separate from the Mail module.

Bitrix24 API: crm.activity.mail.*, crm.{deal,lead,contact,company}.timeline.activity.email.* Scope: crm

Accounts without the method receive 422 METHOD_NOT_YET_AVAILABLE, with error.release set to crm 26.800.1.

List CRM e-mails

GET /v1/deals/:id/emails

GET /v1/leads/:id/emails

GET /v1/contacts/:id/emails

GET /v1/companies/:id/emails

Read one page of e-mails linked to a deal, lead, contact or company. Bitrix24 checks access to the record.

Parameters

Parameter Type Required Description
Parameterid (path) Typeinteger Requiredyes DescriptionRecord identifier from deals, leads, contacts or companies.
Parameterlimit (query) Typeinteger Requiredno DescriptionOne page size. The effective value is returned in meta.limit.
Parameteroffset (query) Typeinteger Requiredno DescriptionOffset from zero. Continue with meta.nextOffset.
ParameterisIncoming (query) Typeboolean Requiredno Descriptiontrue or 1 for incoming, false or 0 for outgoing. Omit for both.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

JavaScript — OAuth application

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

Response fields

Field Description
Fielddata[].id DescriptionIdentifier.
Fielddata[].subject DescriptionE-mail subject.
Fielddata[].dateTime DescriptionDate and time, or null.
Fielddata[].isIncoming DescriptionWhether the e-mail is incoming.
Fielddata[].from DescriptionSender.
Fielddata[].to DescriptionPrimary recipients.
Fieldmeta.returnedCount DescriptionNumber of returned records.
Fieldmeta.hasMore DescriptionWhether another page is available.
Fieldmeta.nextOffset DescriptionNext page offset, or null.
Fieldmeta.limit DescriptionEffective page size.
Fieldmeta.offset DescriptionEffective offset.

Response example

Response structure with neutral sample data.

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
  }
}

Error response example

400 — unknown query parameter:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid type or identifier.
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown query parameter.
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 credentials.
HTTP403 CodeSCOPE_DENIED DescriptionThe crm scope is required.
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe record is absent or inaccessible.
HTTP404 CodeCRM_EMAIL_ACTIVITY_NOT_FOUND DescriptionThe e-mail activity was not found.
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe method is absent on the account. error.release names the required release.
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned an invalid response shape.

Other Bitrix24 refusals retain their original code and message. Common API errors.

Known behavior

These are CRM activity e-mails. The Mail module uses different message identifiers.

Each request reads one page. No collection total is supplied. Continue using meta.hasMore and meta.nextOffset. Filters, sort and field selection are unsupported.

See also