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
from string yes Sender address. Allowed values come from GET /v1/mail/mailboxes/:id/senders
to array of strings yes Recipient addresses
subject string yes Message subject
body string yes Message body
cc array of strings no Carbon copy addresses
bcc array of strings no Blind 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
success boolean true when the request succeeds
data.success boolean true when sending succeeds
data.to array of strings List 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
400 INVALID_PARAMS to is missing or the array is empty — validation[].field equals MISSING_TO
400 INVALID_PARAMS Another required field is missing, or the address in from is not available to the user. The reason is in the validation array
403 SCOPE_DENIED The key lacks the mail scope
401 TOKEN_MISSING The API key has no access tokens configured for the mailbox
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY Invalid API key
401 KEY_INACTIVE The API key is inactive
401 KEY_EXPIRED The API key has expired
422 BITRIX_ERROR Other Bitrix24 errors
429 RATE_LIMITED The platform-wide request limit was exceeded
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

Full list of common API errors — Errors.

See also