# Passerelle SMTP

La passerelle SMTP accepte la soumission de courrier standard et transmet chaque message à [`Notify` de l'API de messagerie v2](/fr/developer/api-reference/messaging-api-v2/notify/) en tant qu'e-mail transactionnel. Utilisez-la lorsqu'un outil de messagerie existant — un MTA, un mailer de framework, un SDK — est plus facile à intégrer qu'une requête JSON à l'API.

<Aside type="note">
La passerelle est uniquement transactionnelle. Pour les segments d'audience, la planification ou les campagnes A/B, appelez directement [`Notify`](/fr/developer/api-reference/messaging-api-v2/notify/).
</Aside>

## Comment ça marche

```
   any SMTP client          smtp gateway              Messaging API v2
   ──────────────── ──────> ──────────────── ──────> ─────────────────
       submission            STARTTLS                gRPC Notify
       AUTH PLAIN            + AUTH PLAIN            Authorization: Token
```

1. Le client se connecte à `smtp.pushwoosh.com` sur le port `587`, met à niveau la connexion vers TLS avec `STARTTLS`, puis s'authentifie avec `AUTH PLAIN`.
2. La passerelle analyse le message MIME et construit une requête `Notify` avec `platforms: ["EMAIL"]` et `message_type: TRANSACTIONAL`.
3. Le jeton d'API de `AUTH PLAIN` est transmis à l'API de messagerie en tant qu'en-tête `Authorization`. La validation du jeton, la correspondance de l'application, l'identité d'envoi et la gestion des rebonds se font tous du côté de l'API.

## Point de terminaison

| Paramètre <div style="width:140px"></div> | Valeur <div style="width:340px"></div> |
|---------|-------|
| Hôte    | `smtp.pushwoosh.com` |
| Port    | `587` (soumission SMTP) |
| TLS     | `STARTTLS` — obligatoire avant `AUTH` |
| Auth    | `AUTH PLAIN` |

## Authentification

`AUTH PLAIN` utilise deux identifiants Pushwoosh.

| Champ AUTH <div style="width:120px"></div> | Valeur Pushwoosh |
|------------|-----------------|
| `username` | [Code d'application](/fr/developer/api-reference/api-identifiers/#application-code), par exemple `XXXXX-XXXXX` |
| `password` | [Jeton d'API serveur](/fr/developer/api-reference/api-access-token/#server-api-token) |

`AUTH` est rejeté en dehors de TLS. Le jeton n'apparaît jamais dans le message — il est uniquement utilisé pour autoriser l'appel `Notify` en amont.

## Correspondance des messages avec Notify

| Champ MIME ou SMTP <div style="width:200px"></div> | Champ Notify |
|--------------------|--------------|
| `RCPT TO`          | `target.users.list` — Pushwoosh résout ces adresses en abonnés |
| `username` AUTH    | `application` |
| En-tête `Subject:`  | `email_payload.subject["default"]` (décodé RFC 2047) |
| En-tête `From:`     | `email_payload.from` — `name` et `email` |
| Partie HTML          | `email_payload.body` (préféré lorsque les deux parties sont présentes) |
| Partie texte brut    | `email_payload.body` (utilisé en l'absence de HTML) |
| `MAIL FROM`        | Ignoré — Pushwoosh substitue sa propre identité d'envoi et gère les rebonds lui-même |

Chaque message est envoyé avec `schedule.send_date: now`.

## Limites

| Limite <div style="width:280px"></div> | Valeur |
|-------|-------|
| Taille maximale du message       | 25 Mio |
| Nombre maximum de destinataires par enveloppe (`RCPT TO`) | 50 |

## Correspondance des erreurs

Les codes de statut gRPC renvoyés par l'API de messagerie sont traduits en codes de réponse SMTP standard afin que tout client SMTP affiche une erreur significative.

| Statut gRPC en amont <div style="width:280px"></div> | Réponse SMTP <div style="width:120px"></div> | Signification |
|----------------------|------------|---------|
| `Unauthenticated`                                          | `535 5.7.8` | Code d'application ou jeton d'API incorrect. |
| `PermissionDenied`                                         | `550 5.7.1` | Le jeton n'a pas les droits pour cette application. |
| `InvalidArgument` / `FailedPrecondition` / `OutOfRange`    | `550 5.6.0` | Contenu MIME incorrect (par exemple, sujet ou corps manquant). |
| `NotFound`                                                 | `550 5.1.1` | Application ou destinataire non trouvé. |
| `ResourceExhausted`                                        | `452 4.5.3` | Limite de débit atteinte — réessayez plus tard. |
| `DeadlineExceeded` / `Unavailable`                         | `451 4.4.1` | Erreur transitoire en amont — réessayez plus tard. |
| toute autre défaillance                                          | `451 4.5.0` | Erreur interne transitoire — réessayez plus tard. |

Les codes de la plage `4xx` sont temporaires et doivent être réessayés par le client ; les codes de la plage `5xx` sont permanents et nécessitent une correction côté client.

## Exemple : envoi avec 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: Bonjour de la part de la passerelle SMTP" \
      --body "Corps en texte brut"
```

L'en-tête `From:` dans le corps MIME est ce qui atteint Pushwoosh — l'enveloppe `--from` (`MAIL FROM`) est ignorée.

## Remarques

- La passerelle est sans état et ne stocke pas les messages. Une fois transmis, la livraison est gérée par l'API de messagerie.
- Les rebonds, les plaintes et les liens de désabonnement sont gérés par Pushwoosh, de la même manière que pour tout autre e-mail transactionnel.
- Pour l'envoi de campagnes (segments, planification, A/B), utilisez directement [`Notify`](/fr/developer/api-reference/messaging-api-v2/notify/) — la passerelle SMTP est uniquement destinée à la soumission.

## Voir aussi

<CardGrid>
  <LinkCard title="Aperçu de l'API de messagerie v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Référence de la charge utile des e-mails" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="Marketing vs transactionnel" href="/product/messaging-channels/marketing-vs-transactional/" />
</CardGrid>