faq
FAQ по email API
Короткие ответы на самые частые вопросы о том, как отправлять письма через curl и HTTP API, какие заголовки нужны, какой формат ответа приходит и как правильно обрабатывать ошибки.
Как отправить письмо через curl
Отправка выполняется обычным POST-запросом на endpoint `/api/messages/send`. В запросе передаётся JSON с полями `from`, `to`, `subject`, `text` и, при необходимости, `html`. Это удобно для терминала, shell-скриптов, cron и любых backend-процессов.
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"
}'Какой заголовок нужен
Обязательный заголовок — `Content-Type: application/json`, чтобы сервер понимал формат тела запроса. Заголовок `key` не нужен для первых 3 бесплатных писем с одного IP, но обязателен дальше и для production-режима.
Какой формат ответа приходит
API отвечает JSON-объектом. В успешном случае вы получаете поля `ok: true`, `code: "sent"`, `message` и объект `data`, где есть `messageId`, список `accepted`, список `rejected`, а также данные отправителя, получателей и темы письма. Такой формат удобен и для людей, и для AI-агентов, потому что ответ можно проверять программно без парсинга HTML.
Как обрабатывать ошибки
При ошибке ориентируйтесь не только на HTTP-статус, но и на поля `ok`, `code` и `message`. Например, `invalid_api_key` означает проблему с ключом доступа, `invalid_request` говорит о неверной структуре JSON или обязательных полях, а `smtp_unavailable` означает, что сервер временно не смог отправить письмо. Для автоматизации лучше обрабатывать эти коды явно и не повторять запрос бесконечно без разбора причины.
Сколько писем можно отправить бесплатно
Без API key доступно до 3 писем с одного IP для тестирования интеграции. После этого сервис вернёт `free_limit_reached`, и для дальнейшей отправки потребуется ключ доступа.