API reference

Базовый публичный endpoint для отправки писем: `POST /api/messages/send`. API предназначен для backend-сервисов, скриптов, curl, cron-задач и AI-агентов, которым нужно отправлять письма программно через HTTP и JSON.

Endpoint работает в двух режимах. Без API key можно отправить до 3 писем бесплатно с одного IP для тестирования. С API key endpoint работает как основной production-канал без тестового лимита в рамках вашего тарифа.

Машинно-читаемая OpenAPI спецификация доступна по адресу `GET /openapi.json`. Это полезно для генерации клиентов, проверки схемы запросов и для AI-агентов, которым нужна формальная структура API, а не только текстовая документация.

Обязательный заголовок: `Content-Type: application/json`. Заголовок `key` нужен для production-режима и обязателен после исчерпания бесплатного лимита.

POST /api/messages/send

Headers:
  Content-Type: application/json

Body:
{
  "from": "ООО Север",
  "to": ["you@example.com"],
  "subject": "Тест API",
  "text": "Письмо отправлено через API",
  "html": "<div><strong>Письмо отправлено через API</strong></div>"
}

Поля запроса:

from    string   обязательное   имя отправителя
to      string[] обязательное   список получателей
subject string   обязательное   тема письма
text    string   обязательное   текстовая версия письма
html    string   необязательное HTML-версия письма

Успешный ответ:

{
  "ok": true,
  "code": "sent",
  "message": "Письмо отправлено.",
  "data": {
    "messageId": "<message-id>",
    "accepted": ["you@example.com"],
    "rejected": [],
    "from": "\"ООО Север\" <ooo.sever@domain>",
    "to": ["you@example.com"],
    "subject": "Тест API"
  }
}

Типичные ошибки:

invalid_api_key   ключ отсутствует или неверен
invalid_request   JSON или обязательные поля некорректны
smtp_unavailable  сервер временно не смог отправить письмо
free_limit_reached бесплатный лимит из 3 писем уже исчерпан

Для устойчивой интеграции проверяйте и HTTP-статус, и поля ответа. Для AI-агентов это особенно важно: решение о повторной попытке должно приниматься по `code`, а не “на глаз”.