SMTP-шлюз

SMTP-шлюз принимает стандартную отправку почты и перенаправляет каждое сообщение в Messaging API v2 Notify как транзакционное email-сообщение. Используйте его, когда существующий почтовый инструмент — MTA, почтовый клиент фреймворка, SDK — проще подключить, чем выполнять JSON-запрос к API.

Примечание

Шлюз предназначен только для транзакционных сообщений. Для сегментов аудитории, планирования или A/B-кампаний вызывайте Notify напрямую.

Как это работает

   любой SMTP-клиент        smtp-шлюз                 Messaging API v2
   ──────────────── ──────> ──────────────── ──────> ─────────────────
       отправка              STARTTLS                gRPC Notify
       AUTH PLAIN            + AUTH PLAIN            Authorization: Token

1. Клиент подключается к smtp.pushwoosh.com по порту 587, обновляет соединение до TLS с помощью STARTTLS, а затем аутентифицируется с помощью AUTH PLAIN.
2. Шлюз анализирует MIME-сообщение и создает запрос Notify с platforms: ["EMAIL"] и message_type: TRANSACTIONAL.
3. API-токен из AUTH PLAIN перенаправляется в Messaging API в качестве заголовка Authorization. Проверка токена, сопоставление приложений, идентификация отправителя и обработка возвратов происходят на стороне API.

Эндпоинт

Настройка	Значение
Хост	smtp.pushwoosh.com
Порт	587 (отправка SMTP)
TLS	STARTTLS — обязательно перед AUTH
Аутентификация	AUTH PLAIN

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

AUTH PLAIN использует два учетных данных Pushwoosh.

Поле AUTH	Значение Pushwoosh
username	Код приложения, например XXXXX-XXXXX
password	Токен Server API

AUTH отклоняется вне TLS. Токен никогда не появляется в сообщении — он используется только для авторизации вышестоящего вызова Notify.

Как сообщения сопоставляются с Notify

Поле MIME или SMTP	Поле Notify
RCPT TO	target.users.list — Pushwoosh преобразует эти адреса в подписчиков
username в AUTH	application
Заголовок Subject:	email_payload.subject["default"] (декодировано по RFC 2047)
Заголовок From:	email_payload.from — name и email
HTML-часть	email_payload.body (предпочтительно, если присутствуют обе части)
Текстовая часть	email_payload.body (используется, если HTML отсутствует)
MAIL FROM	Игнорируется — Pushwoosh подставляет свою собственную идентификацию отправителя и самостоятельно обрабатывает возвраты

Каждое сообщение отправляется с schedule.send_date: now.

Ограничения

Ограничение	Значение
Максимальный размер сообщения	25 МиБ
Максимальное количество получателей на конверт (RCPT TO)	50

Сопоставление ошибок

Коды статуса gRPC, возвращаемые Messaging API, переводятся в стандартные коды ответа SMTP, чтобы любой SMTP-клиент мог отобразить осмысленную ошибку.

Статус gRPC на сервере	Ответ SMTP	Значение
Unauthenticated	535 5.7.8	Неверный код приложения или API-токен.
PermissionDenied	550 5.7.1	Токен не имеет прав для этого приложения.
InvalidArgument / FailedPrecondition / OutOfRange	550 5.6.0	Неверное MIME-содержимое (например, отсутствует тема или тело сообщения).
NotFound	550 5.1.1	Приложение или получатель не найдены.
ResourceExhausted	452 4.5.3	Достигнут лимит скорости — повторите попытку позже.
DeadlineExceeded / Unavailable	451 4.4.1	Временная ошибка на стороне сервера — повторите попытку позже.
любой другой сбой	451 4.5.0	Временная внутренняя ошибка — повторите попытку позже.

Коды в диапазоне 4xx являются временными и должны быть повторены клиентом; коды в диапазоне 5xx являются постоянными и требуют исправления на стороне клиента.

Пример: отправка с помощью swaks

swaks --server smtp.pushwoosh.com:587 \
      --auth-user "XXXXX-XXXXX" \
      --auth-password "YOUR_API_TOKEN" \
      --tls \
      --from from@example.com \
      --to user@example.com \
      --header "Subject: Hello from SMTP gateway" \
      --body "Plain-text body"

Заголовок From: в теле MIME — это то, что доходит до Pushwoosh; конверт --from (MAIL FROM) отбрасывается.

Примечания

• Шлюз не имеет состояния и не хранит сообщения. После пересылки за доставку отвечает Messaging API.
• Возвраты, жалобы и ссылки для отписки обрабатываются Pushwoosh так же, как и для любого другого транзакционного email-сообщения.
• Для отправки кампаний (сегменты, планирование, A/B) используйте Notify напрямую — SMTP-шлюз предназначен только для отправки.

Смотрите также

Обзор Messaging API v2

Notify

Справочник по email-содержимому

Маркетинговые и транзакционные сообщения