# SMTP-шлюз
SMTP-шлюз принимает стандартную отправку почты и перенаправляет каждое сообщение в [Messaging API v2 `Notify`](/ru/developer/api-reference/messaging-api-v2/notify/) как транзакционное email-сообщение. Используйте его, когда существующий почтовый инструмент — MTA, почтовый клиент фреймворка, SDK — проще подключить, чем выполнять JSON-запрос к API.
## Как это работает
```
любой 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` | [Код приложения](/ru/developer/api-reference/api-identifiers/#application-code), например `XXXXX-XXXXX` |
| `password` | [Токен Server API](/ru/developer/api-reference/api-access-token/#server-api-token) |
`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
```bash
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`](/ru/developer/api-reference/messaging-api-v2/notify/) напрямую — SMTP-шлюз предназначен только для отправки.
## Смотрите также