SMTP API электронной почты
API отправки транзакционных писем: подтверждения регистрации, уведомления о заказах и сброс пароля. Доступен через стандартный SMTP и API HTTP.
- Два способа подключения: используйте существующий клиент SMTP без изменения кода или перейдите на API HTTP для более подробных отчётов доставки
- Шаблоны: управляйте централизованно и передавайте только переменные при отправке
- Массовая отправка: несколько получателей в запросе с отдельным отчётом для каждого
- Вебхуки доставки и возвратов: события доставки, возвратов и жалоб в реальном времени для защиты репутации отправителя
POST / GET /api/v1/smtp/*
Обзор
API агрегации SMTP позволяет отправлять почту. Добавьте учётные записи SMTP и отправляйте через единый API. Поддерживает умную ротацию, автоматическое переключение при сбое и квоты.
Купить подписку -> Добавить SMTP -> Создать ключ API -> Вызвать API отправки
Аутентификация
API SMTP использует отдельные ключи модуля (префикс smk_) с двумя способами аутентификации:
Пользовательская консоль -> API агрегации SMTP -> Управление ключами. Сохраните ключ сразу после создания; после закрытия полный ключ больше не показывается.
Отправить письмо
POST /api/v1/smtp/send
Отправьте письмо. Система выбирает лучший SMTP по приоритету, использованию и состоянию.
Поля ответа
Для безопасного повтора передайте заголовок Idempotency-Key: первый успешный результат кэшируется, а повторные запросы с тем же ключом возвращают исходный результат без повторной отправки и двойного списания квоты.
Ответ при запланированной отправке
Если send_at указывает будущее время, письмо не отправляется сразу; создаётся запланированная задача и возвращается следующая структура (квота списывается при фактической отправке):
При превышении суточного или месячного лимита возвращается code: 429. Повысьте тариф или дождитесь обновления квоты.
Пакетная отправка
POST /api/v1/smtp/send/batch
Поля ответа
Максимум получателей в одном запросе равен max_batch_size вашего тарифа (по умолчанию 10); превышение приводит к немедленной ошибке. Суточная и месячная квоты списываются за каждое письмо, а не за запрос; получатели из списка отписавшихся отмечаются как неудачные отправки. Большие пакеты отправляются долго, и запрос может истечь до ответа: передавайте заголовок Idempotency-Key — повтор с тем же значением вернёт первый результат, а не отправит весь пакет заново.
Отправка по шаблону
POST /api/v1/smtp/send/template
Поля ответа
Отправка по шаблону поддерживает постоянную идемпотентность: добавьте заголовок Idempotency-Key: <unique-string>. Намерение отправки сохраняется по сочетанию (пользователь + API-ключ + ключ) и переживает перезапуск процесса или потерю Redis. Правила: (1) повтор с тем же ключом и телом возвращает исходный результат без повторной доставки и списания квоты; (2) тот же ключ с другим телом возвращает конфликт 409 — используйте новый ключ; (3) пока первый запрос обрабатывается (pending), повтор возвращает 409 — повторите позже с тем же ключом; (4) неудачное намерение нельзя открыть заново: возвращается 409 — начните с новым ключом. Без заголовка идемпотентность отключена (обычная отправка).
Запросить квоту
GET /api/v1/smtp/quota
Запросите оставшуюся квоту отправки по текущей подписке.
Запрос статуса отправки
GET /api/v1/smtp/status/:message_id
Запросите статус отправки по message_id, возвращённому API отправки.
Отчёт о недоставке/жалобах
POST /api/v1/smtp/inbound
Сообщите о возврате письма или жалобе: адрес автоматически добавляется в список исключений, а соответствующий журнал отправки помечается. Последующие отправки пропускают адрес для защиты репутации отправителя. Укажите хотя бы email или message_id.
Часто задаваемые вопросы
Мы уже используем SMTP. Нужно ли переписывать код?
Нет. Укажите в существующем клиенте SMTP адрес сервера, порт и учётные данные Tovanix. Переходите на API HTTP только для более подробных отчётов о доставке и возвратах.
Как обрабатывать возвраты и жалобы?
Оба события передаются вебхуками в реальном времени. Добавьте адрес в список исключений и немедленно прекратите отправку на него. Это защищает домен отправителя от попадания в спам.
Связанные страницы: Агрегированный SMTP API · Документация API · SMS-верификация
Загрузка…