Per gli agenti AI: markdown di questa pagina — /docs-content-en/entities/crm-emails.md indice della documentazione — /llms.txt

Gli articoli della documentazione sono attualmente disponibili solo in inglese.

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 DescriptionPage 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 Type Description
Fieldsuccess Typeboolean Descriptiontrue on success.
Fielddata Typearray DescriptionE-mails on the page.
Fielddata[].id Typeinteger DescriptionIdentifier.
Fielddata[].subject Typestring DescriptionE-mail subject.
Fielddata[].dateTime Typestring/null DescriptionDate and time, or null.
Fielddata[].isIncoming Typeboolean DescriptionWhether the e-mail is incoming.
Fielddata[].from Typestring DescriptionSender.
Fielddata[].to Typestring[] DescriptionPrimary recipients.
Fieldmeta.returnedCount Typeinteger DescriptionNumber of returned records.
Fieldmeta.hasMore Typeboolean DescriptionWhether another page is available.
Fieldmeta.nextOffset Typeinteger/null DescriptionNext page offset, or null.
Fieldmeta.limit Typeinteger DescriptionEffective page size.
Fieldmeta.offset Typeinteger 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 only by meta.hasMore and meta.nextOffset. Filtering, sorting and field selection are not supported.

See also