docs

Документация по email API

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

1. Получите доступ и API-ключ

После подключения вы получаете доступ в панель управления, где доступны API-ключ, примеры запросов и журнал отправок. Ключ передаётся в HTTP-заголовке `key`. Храните его только на сервере, не публикуйте в клиентском JavaScript и не вставляйте в открытые репозитории.

2. Отправьте первое письмо через curl

Самый быстрый способ проверить интеграцию — выполнить POST-запрос на `/api/messages/send`. Без API key доступно до 3 бесплатных писем с одного IP. Для production-использования и большего объёма отправок используйте API key из панели.

curl --request POST 'https://vam-pisimo.ru/api/messages/send' \
  --header 'Content-Type: application/json' \
  --data '{
    "from": "ООО Север",
    "to": ["you@example.com"],
    "subject": "Тест API",
    "text": "Письмо отправлено через curl API"
  }'

2.1 OpenAPI спецификация

Для AI-агентов и разработчиков доступна машинно-читаемая спецификация API. Её можно использовать для генерации клиентов, автоматизации, tool calling и проверки структуры запросов.

GET https://vam-pisimo.ru/openapi.json

3. Поддерживаются text и html

Вы можете отправлять простые текстовые письма, HTML-письма или оба варианта сразу. На практике лучше передавать `text` для базовой совместимости и `html` для оформленного письма. Это особенно полезно для уведомлений заказа, регистрации, кодов подтверждения и писем, которые AI-агент формирует автоматически.

3.1 Когда нужен API key

Если вы тестируете сервис руками, через curl или AI-агента, можно начать без ключа и отправить до 3 писем бесплатно. После достижения лимита потребуется API key. Также ключ нужен сразу, если вы хотите использовать сервис как постоянный канал отправки из production-системы.

4. Проверяйте ответ API

Ответ приходит в JSON. Смотрите на поля `ok`, `code`, `message`, `accepted`, `rejected` и `messageId`. Если `ok: true`, письмо принято. Если `ok: false`, ориентируйтесь на `code` и не повторяйте запрос бесконечно без разбора причины.

5. Используйте журнал отправок

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