# Gateway SMTP

O gateway SMTP aceita o envio de e-mail padrão e encaminha cada mensagem para a [API de Mensagens v2 `Notify`](/pt/developer/api-reference/messaging-api-v2/notify/) como um e-mail transacional. Use-o quando uma ferramenta de e-mail existente — um MTA, um mailer de framework, um SDK — for mais fácil de conectar do que uma solicitação JSON para a API.

<Aside type="note">
O gateway é apenas para transações. Para segmentos de público, agendamento ou campanhas A/B, chame a `Notify` diretamente.
</Aside>

## Como funciona

```
   qualquer cliente SMTP    gateway smtp              API de Mensagens v2
   ──────────────── ──────> ──────────────── ──────> ─────────────────
       envio                 STARTTLS                gRPC Notify
       AUTH PLAIN            + AUTH PLAIN            Authorization: Token
```

1. O cliente se conecta a `smtp.pushwoosh.com` na porta `587`, atualiza a conexão para TLS com `STARTTLS` e, em seguida, se autentica com `AUTH PLAIN`.
2. O gateway analisa a mensagem MIME e constrói uma solicitação `Notify` com `platforms: ["EMAIL"]` e `message_type: TRANSACTIONAL`.
3. O token de API do `AUTH PLAIN` é encaminhado para a API de Mensagens como o cabeçalho `Authorization`. A validação do token, a correspondência da aplicação, a identidade de envio e o tratamento de bounces ocorrem no lado da API.

## Endpoint

| Configuração <div style="width:140px"></div> | Valor <div style="width:340px"></div> |
|---------|-------|
| Host    | `smtp.pushwoosh.com` |
| Porta    | `587` (envio SMTP) |
| TLS     | `STARTTLS` — obrigatório antes do `AUTH` |
| Autenticação    | `AUTH PLAIN` |

## Autenticação

`AUTH PLAIN` usa duas credenciais do Pushwoosh.

| Campo AUTH <div style="width:120px"></div> | Valor Pushwoosh |
|------------|-----------------|
| `username` | [Código da aplicação](/pt/developer/api-reference/api-identifiers/#application-code), por exemplo `XXXXX-XXXXX` |
| `password` | [Token de API do servidor](/pt/developer/api-reference/api-access-token/#server-api-token) |

A autenticação (`AUTH`) é rejeitada fora do TLS. O token nunca aparece na mensagem — ele é usado apenas para autorizar a chamada `Notify` upstream.

## Como as mensagens são mapeadas para a Notify

| Campo MIME ou SMTP <div style="width:200px"></div> | Campo Notify |
|--------------------|--------------|
| `RCPT TO`          | `target.users.list` — O Pushwoosh resolve esses endereços para assinantes |
| `username` do AUTH    | `application` |
| Cabeçalho `Subject:`  | `email_payload.subject["default"]` (decodificado RFC 2047) |
| Cabeçalho `From:`     | `email_payload.from` — `name` e `email` |
| Parte HTML          | `email_payload.body` (preferido quando ambas as partes estão presentes) |
| Parte de texto simples    | `email_payload.body` (usado quando o HTML está ausente) |
| `MAIL FROM`        | Ignorado — O Pushwoosh substitui sua própria identidade de envio e lida com os bounces |

Toda mensagem é enviada com `schedule.send_date: now`.

## Limites

| Limite <div style="width:280px"></div> | Valor |
|-------|-------|
| Tamanho máximo da mensagem       | 25 MiB |
| Máximo de destinatários por envelope (`RCPT TO`) | 50 |

## Mapeamento de erros

Os códigos de status gRPC retornados pela API de Mensagens são traduzidos para códigos de resposta SMTP padrão para que qualquer cliente SMTP exiba um erro significativo.

| Status gRPC upstream <div style="width:280px"></div> | Resposta SMTP <div style="width:120px"></div> | Significado |
|----------------------|------------|---------|
| `Unauthenticated`                                          | `535 5.7.8` | Código da aplicação ou token de API inválido. |
| `PermissionDenied`                                         | `550 5.7.1` | O token não tem permissão para esta aplicação. |
| `InvalidArgument` / `FailedPrecondition` / `OutOfRange`    | `550 5.6.0` | Conteúdo MIME inválido (por exemplo, assunto ou corpo ausente). |
| `NotFound`                                                 | `550 5.1.1` | Aplicação ou destinatário não encontrado. |
| `ResourceExhausted`                                        | `452 4.5.3` | Limite de taxa atingido — tente novamente mais tarde. |
| `DeadlineExceeded` / `Unavailable`                         | `451 4.4.1` | Erro transitório no upstream — tente novamente mais tarde. |
| qualquer outra falha                                          | `451 4.5.0` | Erro interno transitório — tente novamente mais tarde. |

Códigos na faixa `4xx` são temporários e devem ser tentados novamente pelo cliente; códigos na faixa `5xx` são permanentes e exigem uma correção no lado do cliente.

## Exemplo: enviar com 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"
```

O cabeçalho `From:` no corpo MIME é o que chega ao Pushwoosh — o envelope `--from` (`MAIL FROM`) é descartado.

## Notas

- O gateway é stateless e não armazena mensagens. Uma vez encaminhada, a entrega é de responsabilidade da API de Mensagens.
- Bounces, reclamações e links de cancelamento de inscrição são tratados pelo Pushwoosh, da mesma forma que para qualquer outro e-mail transacional.
- Para envio de campanhas (segmentos, agendamento, A/B), use a `Notify` diretamente — o gateway SMTP é apenas para envio.

## Veja também

<CardGrid>
  <LinkCard title="Visão geral da API de Mensagens v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Referência de payload de e-mail" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="Marketing vs. transacional" href="/product/messaging-channels/marketing-vs-transactional/" />
</CardGrid>