# 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`](/es/developer/api-reference/messaging-api-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.

<Aside type="note">
La pasarela es solo para transacciones. Para segmentos de audiencia, programación o campañas A/B, llame a [`Notify`](/es/developer/api-reference/messaging-api-v2/notify/) directamente.
</Aside>

## 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 <div style="width:140px"></div> | Valor <div style="width:340px"></div> |
|---------|-------|
| 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 <div style="width:120px"></div> | Valor de Pushwoosh |
|------------|-----------------|
| `username` | [Código de aplicación](/es/developer/api-reference/api-identifiers/#application-code), por ejemplo `XXXXX-XXXXX` |
| `password` | [Token de API del servidor](/es/developer/api-reference/api-access-token/#server-api-token) |

`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 <div style="width:200px"></div> | 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 <div style="width:280px"></div> | 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 <div style="width:280px"></div> | Respuesta SMTP <div style="width:120px"></div> | 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

```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"
```

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`](/es/developer/api-reference/messaging-api-v2/notify/) directamente — la pasarela SMTP es solo para envío.

## Véase también

<CardGrid>
  <LinkCard title="Resumen de la API de mensajería v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Referencia de la carga útil del correo electrónico" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="Marketing vs. transaccional" href="/product/messaging-channels/marketing-vs-transactional/" />
</CardGrid>