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
Загрузка…