INTEGRITY Документация

← Cloudflare Email Service / email-service / api / send-emails

REST API

REST API позволяет отправлять письма из любого приложения с помощью стандартного HTTP-запроса к POST /accounts/{account_id}/email/sending/send. Используйте его из любого бэкенда, бессерверной функции или CI/CD-конвейера. Привязка Cloudflare Workers для этого не требуется.

Полную спецификацию OpenAPI см. в Справочник Email Sending API.

Cloudflare также предоставляет официальные SDK для REST API: Node, Python, а также Go.

Аутентификация

Аутентифицируйтесь с помощью API-токен Cloudflare у которого есть разрешение на отправку писем. Включите его в Authorization заголовок:

Authorization: Bearer <API_TOKEN>

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

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "[email protected]",
    "from": "[email protected]",
    "subject": "Welcome to our service!",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
    "text": "Welcome! Thanks for signing up."
  }'

О нескольких получателях, CC/BCC и именованных адресах см. Указание получателей.

Вложения

Отправляйте файлы, указав содержимое в кодировке base64 в attachments массив. Общий размер сообщения не должен превышать 5 MiB (включая вложения).

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "[email protected]",
    "from": "[email protected]",
    "subject": "Your Invoice",
    "html": "<h1>Invoice attached</h1><p>Please find your invoice attached.</p>",
    "attachments": [
      {
        "content": "JVBERi0xLjQKJeLjz9MK...",
        "filename": "invoice-12345.pdf",
        "type": "application/pdf",
        "disposition": "attachment"
      }
    ]
  }'

Об встроенных изображениях и загрузке файлов см. Вложения писем.

Пользовательские заголовки

Настройте пользовательские заголовки для группировки писем в цепочки, управления рассылками или отслеживания. См. справочник по заголовкам писем для получения полного списка разрешённых заголовков.

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/email/sending/send" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "[email protected]",
    "from": "[email protected]",
    "subject": "Your weekly digest",
    "html": "<h1>Weekly Digest</h1>",
    "headers": {
      "List-Unsubscribe": "<https://yourdomain.com/unsubscribe?id=abc123>",
      "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
      "X-Campaign-ID": "weekly-digest-2026-03"
    }
  }'

Ответ

Успешный ответ возвращает статус доставки для каждого получателя:

{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"delivered": ["[email protected]"],
		"permanent_bounces": [],
		"queued": []
	}
}

Обработка ошибок

REST API возвращает стандартные ответы об ошибках Cloudflare API. Неудачный запрос возвращает errors массив с числовыми кодами ошибок и сообщениями, пригодными для машинной обработки:

{
	"success": false,
	"errors": [
		{
			"code": 10001,
			"message": "email.sending.error.invalid_request_schema"
		}
	],
	"messages": [],
	"result": null
}

Коды ошибок REST API:

HTTP-статус Код Сообщение Описание
400 10001 email.sending.error.invalid_request_schema Неверный формат запроса
400 10200 email.sending.error.email.too_big Письмо превышает ограничение по размеру
400 10201 email.sending.error.email.no_content_length Отсутствует длина содержимого
400 10202 email.sending.error.email.invalid Недопустимое содержимое письма
401 10101 email.sending.error.authentication.unauthorized Отсутствует или недействителен токен API
401 10103 email.sending.error.authentication.bad_token_type Неверный тип токена для этой конечной точки
403 10102 email.sending.error.authentication.forbidden У токена нет разрешения на отправку
403 10105 email.sending.error.authentication.not_entitled Аккаунт не имеет права использовать Email Sending
403 10203 email.sending.error.email.sending_disabled Отправка отключена для этой зоны или аккаунта
404 10000 email.sending.error.not_found Ресурс не найден
429 10004 email.sending.error.throttled Превышено ограничение скорости
500 10002 email.sending.error.internal_server Внутренняя ошибка сервера
500 10003 email.sending.error.not_implemented Операция не реализована
503 10100 email.sending.error.authentication.upstream Служба аутентификации временно недоступна

Следующие шаги