Pasarela SMTP

La pasarela SMTP acepta el envío de correo estándar y reenvía cada mensaje a la API de mensajería v2 Notify como un correo electrónico transaccional. Úsela cuando una herramienta de correo existente —un MTA, un cliente de correo de un framework, un SDK— es más fácil de conectar que una solicitud JSON a la API.

Nota

La pasarela es solo para transacciones. Para segmentos de audiencia, programación o campañas A/B, llame a Notify directamente.

Cómo funciona

   cualquier cliente SMTP     pasarela smtp             API de mensajería v2
   ───────────────────── ──────> ──────────────── ──────> ───────────────────
       envío                   STARTTLS                gRPC Notify
       AUTH PLAIN              + AUTH PLAIN            Authorization: Token

1. El cliente se conecta a smtp.pushwoosh.com en el puerto 587, actualiza la conexión a TLS con STARTTLS, y luego se autentica con AUTH PLAIN.
2. La pasarela analiza el mensaje MIME y construye una solicitud Notify con platforms: ["EMAIL"] y message_type: TRANSACTIONAL.
3. El token de API de AUTH PLAIN se reenvía a la API de mensajería como la cabecera Authorization. La validación del token, la coincidencia de la aplicación, la identidad de envío y el manejo de rebotes ocurren del lado de la API.

Endpoint

Configuración	Valor
Host	smtp.pushwoosh.com
Puerto	587 (envío SMTP)
TLS	STARTTLS — obligatorio antes de AUTH
Autenticación	AUTH PLAIN

Autenticación

AUTH PLAIN utiliza dos credenciales de Pushwoosh.

Campo AUTH	Valor de Pushwoosh
username	Código de aplicación, por ejemplo XXXXX-XXXXX
password	Token de API del servidor

AUTH se rechaza fuera de TLS. El token nunca aparece en el mensaje — solo se utiliza para autorizar la llamada Notify ascendente.

Cómo se mapean los mensajes a Notify

Campo MIME o SMTP	Campo Notify
RCPT TO	target.users.list — Pushwoosh resuelve estas direcciones a suscriptores
AUTH username	application
Cabecera Subject:	email_payload.subject["default"] (decodificado RFC 2047)
Cabecera From:	email_payload.from — name y email
Parte HTML	email_payload.body (preferido cuando ambas partes están presentes)
Parte de texto plano	email_payload.body (usado cuando HTML está ausente)
MAIL FROM	Ignorado — Pushwoosh sustituye su propia identidad de envío y maneja los rebotes por sí mismo

Cada mensaje se envía con schedule.send_date: now.

Límites

Límite	Valor
Tamaño máximo del mensaje	25 MiB
Máximo de destinatarios por sobre (RCPT TO)	50

Mapeo de errores

Los códigos de estado gRPC devueltos por la API de mensajería se traducen a códigos de respuesta SMTP estándar para que cualquier cliente SMTP muestre un error significativo.

Estado gRPC ascendente	Respuesta SMTP	Significado
Unauthenticated	535 5.7.8	Código de aplicación o token de API incorrecto.
PermissionDenied	550 5.7.1	El token no tiene derechos para esta aplicación.
InvalidArgument / FailedPrecondition / OutOfRange	550 5.6.0	Contenido MIME incorrecto (por ejemplo, falta el asunto o el cuerpo).
NotFound	550 5.1.1	No se encontró la aplicación o el destinatario.
ResourceExhausted	452 4.5.3	Límite de tasa alcanzado — reintente más tarde.
DeadlineExceeded / Unavailable	451 4.4.1	Error transitorio ascendente — reintente más tarde.
cualquier otro fallo	451 4.5.0	Error interno transitorio — reintente más tarde.

Los códigos en el rango 4xx son temporales y el cliente debe reintentarlos; los códigos en el rango 5xx son permanentes y requieren una corrección del lado del cliente.

Ejemplo: enviar con 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"

La cabecera From: en el cuerpo MIME es lo que llega a Pushwoosh — el sobre --from (MAIL FROM) se descarta.

Notas

• La pasarela no tiene estado y no almacena mensajes. Una vez reenviado, la entrega es propiedad de la API de mensajería.
• Los rebotes, quejas y enlaces para darse de baja son manejados por Pushwoosh, igual que para cualquier otro correo electrónico transaccional.
• Para el envío de campañas (segmentos, programación, A/B), utilice Notify directamente — la pasarela SMTP es solo para envío.

Véase también

Resumen de la API de mensajería v2

Notify

Referencia de la carga útil del correo electrónico

Marketing vs. transaccional