Tovanix
Tovanix

API отправки почты

Отправляйте письма со своего домена на стороне сервера с теми же квотами, оплатой и ограничениями, что и в консоли. Домен отправителя должен точно совпадать с подключённым активным доменом отправки.

  • Авторизация: тот же пользовательский API-ключ, что и для остальных открытых API платформы
  • Отправка: POST /api/v1/mail/send; ответ сгруппирован по получателям, а bounced_addrs — единственное основание для очистки списка
  • Идемпотентность: при заголовке Idempotency-Key повторные запросы с одним ключом выполняют отправку ровно один раз, без повторной доставки и оплаты
  • Цепочки: передайте in_reply_to и полную цепочку references, чтобы ответы попали в исходную переписку получателя
  • Квоты и домены: запрашивайте оставшуюся суточную квоту и доступные домены отправки для ограничения скорости в своей системе
  • Примеры: минимальные рабочие cURL / Node.js / Python / Go / PHP, каждый с идемпотентностью и обработкой постоянных отказов

POST / GET /api/v1/mail/*

Обзор

Отправляйте с собственных доменов на стороне сервера. Квоты, оплата и ограничения полностью совпадают с консолью.

Включите отправку почты в консоли и подключите хотя бы один домен со статусом «Активен». Отправка с неактивного домена отклоняется.

Аутентификация

Использует тот же API-ключ аккаунта, что и остальные сервисы платформы. Создайте его в разделе Инструменты и настройки → Управление API.

Консоль → Инструменты и настройки → Управление API → Создать ключ. Один ключ работает с API энергии, виртуальных карт, почты и обменных курсов; доступные интерфейсы зависят от выданных разрешений.

Отправка писем

POST /api/v1/mail/send

Домен From должен точно совпадать с подключённым активным доменом отправки.

Ограничения отправки

  • В to + cc + bcc должно быть не более 50 получателей суммарно
  • 5 MiB на письмо вместе с вложениями (размер после декодирования)
  • 998 символов (учитываются символы, не байты — темы с не-ASCII символами не ограничиваются дополнительно)
  • До 32 вложений; встроенные вложения должны содержать content_id
  • Всего 16 KB пользовательских заголовков, 2048 байт на значение заголовка

Ответ

Результаты сгруппированы по получателям, а не сведены к одному общему признаку успеха.

При отправке пяти получателям возможны 2 доставки, 1 письмо в очереди и 2 окончательных возврата. bounced_addrs — единственный источник для очистки списка: вебхука возвратов нет. Если отбросить поле, информация теряется, и вы продолжите отправлять на неработающие адреса и платить за это.

Идемпотентность

С заголовком Idempotency-Key повтор того же ключа приводит только к одной отправке.

Всякий раз, когда вызов может повторяться автоматически: тайм-ауты, очереди задач, повторы SDK. Без него один сетевой сбой приводит к двум копиям письма и двойной оплате, которые нельзя отменить. Используйте бизнес-ключ, например номер заказа.

Объединение в цепочки

При ответе передавайте in_reply_to и references, чтобы письмо попало в исходную переписку; без них каждый ответ создаёт новую цепочку у получателя. Передавайте полную цепочку references: с одним in_reply_to некоторые клиенты разделяют переписки длиннее двух писем.

Квота и домены

Проверяйте оставшийся суточный объём и доступные домены отправки, чтобы ограничивать частоту на своей стороне.

Примеры кода

Минимальные рабочие примеры для каждого языка с обработкой идемпотентности и окончательных возвратов.

Отправка почты платная. Новые API-ключи по умолчанию требуют подписи платных интерфейсов, поэтому все примеры ниже используют версию 2 (передавайте X-Sign-Version: 2). Строка подписи — 7 строк, объединённых через \n без завершающего переноса: NEXCORE-HMAC-SHA256-V2, timestamp, nonce, метод в верхнем регистре, путь, строка запроса и SHA-256 тела в hex нижнего регистра. X-Signature — HMAC-SHA256(Secret Key, строка подписи) в hex нижнего регистра. timestamp — время Unix в секундах, nonce — не более 64 байт; строка запроса без начального "?" должна точно совпадать с отправленной (пустая строка при отсутствии). Хеш тела вычисляется по точным отправляемым байтам. Если отключить требование подписи для платных операций и конфиденциальных данных, работают и одни X-API-Key + X-Secret-Key, но это не рекомендуется.

Часто задаваемые вопросы

Означает ли HTTP 200, что все получатели получили письмо?

Нет. Результаты разделены по получателям: из пяти адресатов 2 могут получить письмо, 1 — остаться в очереди, а 2 — получить постоянный отказ. Вебхука отказов нет, поэтому bounced_addrs — единственная основа очистки списка. Немедленно прекратите отправку на эти адреса.

Когда требуется Idempotency-Key?

Всегда, когда вызов может повторяться автоматически: после тайм-аута, повторной выдачи задачи из очереди или встроенного повтора SDK. Без него краткий сетевой сбой может привести к двум письмам и двойной оплате, которые нельзя отменить. Используйте бизнес-ключ, например идентификатор заказа.

Связанные страницы: Документация API · Агрегированный SMTP API · Использование API агрегации SMTP

Загрузка…