Интеграция для AI

Подключение почты для AI-агентов

Машиночитаемый маршрут для AI-агентов и ассистентов, которым нужно добавить транзакционную почту в чужой проект: что вызывать, в каком порядке и какие проверки обязательны перед каждой отправкой.

Обновлено 24 июля 2026Скачать OpenAPI 3.1

Перед тем как писать код

Попросите у пользователя API-ключ проекта или предложите создать sandbox-ключ на https://app.srs-postline.com/ru/login — никогда не придумывайте, не угадывайте и не переиспользуйте ключ из другого проекта.
Кладите ключ в серверную переменную окружения. Не размещайте его во frontend-коде, мобильном приложении, публичном репозитории или закоммиченном .env.
Используйте srs_live_ ключ. До проверки домена отправляйте с sandbox@srs-postline.com только на email участника проекта; после проверки домена разрешены внешние получатели в пределах квот.
Прочитайте /llms.txt и openapi/postline.yaml до генерации запросов — не угадывайте названия полей и эндпоинты.

Минимальная отправка

POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <стабильный-id-на-действие>
Content-Type: application/json

{
  "from": "Sender Name <info@example.com>",
  "to": ["user@example.net"],
  "subject": "Тема",
  "html": "<p>Текст</p>",
  "text": "Текст"
}

Проверки перед каждой отправкой

Всегда передавайте Idempotency-Key, полученный из вызвавшего действия (ID заказа, ID события) — иначе повтор запроса продублирует письмо.
Никогда не кладите OTP-коды, токены сброса пароля и другие секреты в поля, которые логируются или пересылаются за пределы тела письма.
Запрашивайте минимально необходимый scope ключа (для отправки достаточно emails:send; не запрашивайте domains:write или api_keys:write без необходимости).
Не превышайте 100 получателей на вызов. Текущий API не принимает вложения и произвольные заголовки; отклоняйте файлы или передавайте ссылку, не создавая впечатление, что файл прикреплён.
Не повторяйте запрос молча при ошибках 4xx. Безопасно повторять только 429 и 503, и только с задержкой (backoff).

Обработка каждого кода ответа

202 — принято в очередь, ещё не доставлено. Сохраните id, если понадобится проверить статус позже.
400 — невалидный payload; исправьте запрос, не повторяйте как есть.
401 — неверный или истёкший ключ; остановитесь и сообщите пользователю, не придумывайте новый ключ.
403 — не хватает scope или домен отправителя ещё не верифицирован; попросите пользователя подтвердить домен.
422 — получатель в suppression-листе (был bounce/complaint); не повторяйте отправку этому адресату.
429 — превышен лимит; повторите позже с задержкой, не зацикливайтесь.
503 — очередь недоступна; повторите с задержкой, не переключайтесь на неофициальный способ отправки.

Если задача включает приём событий

Регистрируйте webhook-эндпоинт только по HTTPS. Пересчитывайте подпись самостоятельно перед тем, как доверять payload — не пропускайте проверку, даже если запрос «выглядит внутренним».

signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)

сравнивайте с заголовком Postline-Signature (constant-time compare)
отклоняйте, если Postline-Timestamp вне допустимого окна
сохраняйте event_id и обрабатывайте каждое событие ровно один раз

Машиночитаемые ссылки

/llms.txt — сжатый свод этих правил для контекста агента.
/openapi/postline.yaml — полная OpenAPI 3.1 схема всех эндпоинтов.
/ru/api/ — API reference для человека.
/ru/webhooks/ — подпись и retry вебхуков.

Актуальная модель доступа

Текущие ключи dashboard используют префикс srs_live_. До проверки клиентского From-домена общий sandbox-отправитель может писать только участникам проекта. После проверки DNS внешняя отправка ограничивается квотами тарифа, suppression, лимитами получателей и abuse-контролями. Ответ 202 означает очередь, а не доставку.

Материалы для интеграции

Используйте пошаговое руководство для людей и AI-агентов, а OpenAPI — как источник истины по полям API.