/api/v1/mailAuth: X-API-Key с permission mail:send или mail:*
Response envelope: формат ответа B (см. api-overview.html)
---
Отправка письма или постановка в outbox-очередь.
Headers:
| Header | Обяз. | Описание |
|---|---|---|
X-API-Key | да | API-ключ с mail:send |
ключ идемпотентности | нет | UUID для идемпотентности (альтернатива body-полю) |
Content-Type | да | application/json |
Request body (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 | Отклонено провайдером |
---
Статус outbox-задачи.
Auth: X-API-Key (mail:send)
Path params:
| Param | Описание |
|---|---|
job_id | ID задачи из /send |
Response 200 — data (MailJobStatusResponseData):
| Поле | Тип | Описание | |
|---|---|---|---|
job_id | string | ||
status | string | pending / sent / failed / unknown | |
attempts | int | число попыток | |
last_error | string \ | null | последняя ошибка |
sent_at | string \ | null | ISO timestamp |
Errors: 404 not_found, 503 mail_unavailable
---
POST /api/v1/mail/send HTTP/1.1
X-API-Key: csk_live_xxxxxxxx
Content-Type: application/json
ключ идемпотентности: 550e8400-e29b-41d4-a716-446655440000
{
"to": ["user@example.com"],
"subject": "Welcome",
"template": "welcome",
"variables": { "name": "Alex" },
"sync": false
}