Gateway SMTP

O gateway SMTP aceita o envio de e-mail padrão e encaminha cada mensagem para a API de Mensagens 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.

Nota

O gateway é apenas para transações. Para segmentos de público, agendamento ou campanhas A/B, chame a Notify diretamente.

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	Valor
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	Valor Pushwoosh
username	Código da aplicação, por exemplo XXXXX-XXXXX
password	Token de API do servidor

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	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	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	Resposta SMTP	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

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

Visão geral da API de Mensagens v2

Notify

Referência de payload de e-mail

Marketing vs. transacional