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

Send a CRM e-mail

POST /v1/deals/:id/emails

POST /v1/leads/:id/emails

POST /v1/contacts/:id/emails

POST /v1/companies/:id/emails

Send a real e-mail from CRM using an available sender. The e-mail is linked to the specified CRM record.

Parameters

Parameter Type Required Description
Parameterid (path) Typeinteger Requiredyes DescriptionRecord identifier from deals, leads, contacts or companies.

Request body

Field Type Required Description
Fieldto Typestring[] Requiredyes DescriptionPrimary recipients.
Fieldsubject Typestring or null Requiredno DescriptionE-mail subject.
Fieldbody Typestring Requiredyes DescriptionE-mail body.
Fieldcc Typestring[] or null Requiredno DescriptionCC recipients.
Fieldbcc Typestring[] or null Requiredno DescriptionBCC recipients.
Fieldfrom Typestring or null Requiredno DescriptionAvailable sender address.
FieldsenderId Typeinteger or null Requiredno DescriptionSender identifier accepted by Bitrix24.
FieldmailboxId Typeinteger or null Requiredno DescriptionIdentifier from mailboxes.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/deals/741/emails" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": ["reader@example.com"], "body": "Hello", "subject": "Integration request"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/deals/741/emails" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": ["reader@example.com"], "body": "Hello", "subject": "Integration request"}'

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/deals/741/emails', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"to": ["reader@example.com"], "body": "Hello", "subject": "Integration request"}),
})
const result = await response.json()

JavaScript — OAuth application

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/deals/741/emails', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"to": ["reader@example.com"], "body": "Hello", "subject": "Integration request"}),
})
const result = await response.json()

Response fields

Field Description
Fielddata.activityId DescriptionCreated activity identifier. Read it through e-mail content.
Fielddata.parentActivityId DescriptionOriginal activity identifier, or null.
Fielddata.from DescriptionSender.
Fielddata.to DescriptionPrimary recipients.
Fielddata.cc DescriptionCC recipients.
Fielddata.bcc DescriptionBCC recipients.
Fielddata.isSyncedToImap DescriptionWhether a copy was saved in the connected mailbox.
Fielddata.warnings DescriptionSending and synchronization warnings.

Response example

Response structure with neutral sample data.

JSON 
{
  "success": true,
  "data": {
    "activityId": 1204,
    "parentActivityId": null,
    "from": "sender@example.com",
    "to": [
      "reader@example.com"
    ],
    "cc": [],
    "bcc": [],
    "isSyncedToImap": false,
    "warnings": []
  }
}

Error response example

400 — unknown query parameter or a missing required field:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "to and body are required"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid type or identifier.
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown query parameter.
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionMissing required body field.
HTTP400 CodeUNKNOWN_FIELD DescriptionUnknown body field.
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 credentials.
HTTP403 CodeSCOPE_DENIED DescriptionThe crm scope is required.
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key access mode forbids writes.
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.

Never blindly retry after a timeout, interrupted response or 502: the real e-mail may already have been sent. Read the e-mail list first.

See also