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

Send message

POST /v1/mail/messages

Sends a message on behalf of the specified sender. The sent message is saved to the mailbox's Sent folder.

Request fields (body)

Field Type Required Description
Fieldfrom Typestring Requiredyes DescriptionSender address. Allowed values come from GET /v1/mail/mailboxes/:id/senders
Fieldto Typearray of strings Requiredyes DescriptionRecipient addresses
Fieldsubject Typestring Requiredyes DescriptionMessage subject
Fieldbody Typestring Requiredyes DescriptionMessage body
FieldmailboxId Typeinteger Requiredno DescriptionMailbox ID from GET /v1/mail/mailboxes. Selects the sending mailbox for from, taking precedence over senderId when both are supplied
FieldsenderId Typeinteger Requiredno DescriptionSender ID from GET /v1/mail/mailboxes/:id/senders. Selects the sender for from when mailboxId is omitted
Fieldcc Typearray of strings Requiredno DescriptionCarbon copy addresses
Fieldbcc Typearray of strings Requiredno DescriptionBlind carbon copy addresses

Examples

curl — personal key

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://vibecode.bitrix24.com/v1/mail/messages \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Message subject",
    "body": "Message body"
  }'

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" \
  https://vibecode.bitrix24.com/v1/mail/messages \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Message subject",
    "body": "Message body"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/mail/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'sender@example.com',
    to: ['recipient@example.com'],
    subject: 'Message subject',
    body: 'Message body',
  }),
})
const data = await res.json()
console.log(data.data.to)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/mail/messages', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'sender@example.com',
    to: ['recipient@example.com'],
    subject: 'Message subject',
    body: 'Message body',
  }),
})
const data = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata.success Typeboolean Descriptiontrue when sending succeeds
Fielddata.to Typearray of strings DescriptionList of addresses the message was sent to

Response example

JSON 
{
  "success": true,
  "data": {
    "success": true,
    "to": ["recipient@example.com"]
  }
}

Error response example

400 — recipients are missing:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request object validation failed",
    "validation": [
      {
        "field": "MISSING_TO",
        "message": "Parameter \"to\" is required and must be a non-empty array."
      }
    ]
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionto is missing or the array is empty — validation[].field equals MISSING_TO
HTTP400 CodeINVALID_PARAMS DescriptionAnother required field is missing, or the address in from is not available to the user. The reason is in the validation array
HTTP400 CodeINVALID_PARAMS DescriptionSending failed — error.validation[].field is MESSAGE_SEND_FAILED. Check sender availability, whether from matches the selected mailbox or sender, and the mailbox state. The reason is in error.validation[].message. Fix the cause before retrying
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the mail scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no access tokens configured for the mailbox
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is inactive
HTTP401 CodeKEY_EXPIRED DescriptionThe API key has expired
HTTP422 CodeBITRIX_ERROR DescriptionOther Bitrix24 errors
HTTP429 CodeRATE_LIMITED DescriptionThe platform-wide request limit was exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable

Full list of common API errors — Errors.

See also