POST /api/v1/mail/send

Отправка письма или постановка в outbox-очередь.

Base URL: https://<host>/ (пример: http://localhost:5000). Соглашения, обзор Public API, Swagger UI.

Headers:

Header	Обяз.	Описание
`X-API-Key`	да	API-ключ с `mail:send`
`ключ идемпотентности`	нет	UUID для идемпотентности (альтернатива body-полю)
`Content-Type`	да	`application/json`

Тело запроса (MailSendRequestSchema):

Поле	Тип	Обяз.	Описание
`to`	string[]	да	1–50 получателей
`cc`	string[]	нет	max 50
`subject`	string	да	1–512, sanitized
`text`	string	*	plain text, max 100 000
`html`	string	*	HTML, max 200 000
`template`	string	*	имя шаблона, max 128
`variables`	object	нет	переменные шаблона
`idempotency_key`	string	нет	max 128
`sync`	boolean	нет	`true` — синхронная отправка, default `false`

*Обязательно: text и/или html, либо template.

Response 200 (sync) / 202 (async) — data:

Поле	Тип	Описание
`job_id`	string \	null	ID задачи outbox
`sync`	bool	режим отправки
`recipient_count`	int	to + cc count

Error codes:

Code	HTTP	Описание
`unauthorized`	401	Нет/неверный API key
`validation_error`	400	Ошибка проверка формата данных
`mail_unavailable`	503	Mail provider недоступен
`mail_not_configured`	503	Mail не настроен
`mail_rate_limited`	429	Rate limit
`mail_rejected`	502	Отклонено провайдером

Заголовки запроса

Заголовок	Обяз.	Описание
`X-API-Key`	да	Ключ с scope mail:send
`Content-Type`	да	application/json

Минимальный пример запроса

{
  "to": ["user@example.com"],
  "subject": "Welcome",
  "text": "Hello!",
  "sync": false
}

Пример успешного ответа

{
  "success": true,
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "sync": false,
    "recipient_count": 1
  }
}

Пример ошибки

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Пример curl

curl -X POST http://localhost:5000/api/v1/mail/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":["user@example.com"],"subject":"Welcome","text":"Hello!","sync":false}'

См. также: GET job status.