Tovanix
Tovanix

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-верификация

Загрузка…