Для AI-агентов: markdown этой страницы — /docs-content/mail/messages/send.md индекс документации — /llms.txt

Отправить письмо

POST /v1/mail/messages

Отправляет письмо от имени указанного отправителя. Отправленное письмо сохраняется в папку Отправленные почтового ящика.

Поля запроса (body)

Поле Тип Обяз. Описание
from string да Адрес отправителя. Допустимые значения — из GET /v1/mail/mailboxes/:id/senders
to array of strings да Адреса получателей
subject string да Тема письма
body string да Текст письма
mailboxId integer нет ID почтового ящика из GET /v1/mail/mailboxes. Выбирает ящик отправки для адреса from, при передаче обоих селекторов имеет приоритет над senderId
senderId integer нет ID отправителя из GET /v1/mail/mailboxes/:id/senders. Выбирает отправителя для адреса from, если mailboxId не передан
cc array of strings нет Адреса для копии
bcc array of strings нет Адреса для скрытой копии

Примеры

curl — личный ключ

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://vibecode.bitrix24.tech/v1/mail/messages \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Тема письма",
    "body": "Текст письма"
  }'

curl — OAuth-приложение

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.tech/v1/mail/messages \
  -d '{
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Тема письма",
    "body": "Текст письма"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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: 'Тема письма',
    body: 'Текст письма',
  }),
})
const data = await res.json()
console.log(data.data.to)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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: 'Тема письма',
    body: 'Текст письма',
  }),
})
const data = await res.json()

Поля ответа

Поле Тип Описание
success boolean true при успешном выполнении запроса
data.success boolean true при успешной отправке
data.to array of strings Список адресов, которым отправлено письмо

Пример ответа

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

Пример ответа при ошибке

400 — не переданы получатели:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Ошибка при валидации объекта запроса",
    "validation": [
      {
        "field": "MISSING_TO",
        "message": "Parameter \"to\" is required and must be a non-empty array."
      }
    ]
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Не передан to или массив пуст — validation[].field равен MISSING_TO
400 INVALID_PARAMS Не передано другое обязательное поле или адрес в from недоступен пользователю. Причина — в массиве validation
400 INVALID_PARAMS Отправка не выполнена — error.validation[].field равен MESSAGE_SEND_FAILED. Проверьте доступность отправителя, соответствие from выбранному ящику или отправителю и состояние ящика. Причина — в error.validation[].message, повтор без исправления причины не поможет
403 SCOPE_DENIED Ключу не хватает скоупа mail
401 TOKEN_MISSING У API-ключа не настроены токены доступа к почтовому ящику
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Ключ не опознан: такой строки на платформе нет
401 KEY_INACTIVE API-ключ неактивен
401 KEY_EXPIRED Срок действия API-ключа истёк
422 BITRIX_ERROR Прочие ошибки Битрикс24
429 RATE_LIMITED Превышен общий лимит запросов платформы
502 BITRIX_UNAVAILABLE Битрикс24 недоступен

Полный список общих ошибок API — Ошибки.

Смотрите также