Passerelle SMTP

La passerelle SMTP accepte la soumission de courrier standard et transmet chaque message à Notify de l’API de messagerie v2 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.

Note

La passerelle est uniquement transactionnelle. Pour les segments d’audience, la planification ou les campagnes A/B, appelez directement Notify.

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	Valeur
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	Valeur Pushwoosh
username	Code d’application, par exemple XXXXX-XXXXX
password	Jeton d’API serveur

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	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	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	Réponse SMTP	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

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 — la passerelle SMTP est uniquement destinée à la soumission.

Voir aussi

Aperçu de l'API de messagerie v2

Notify

Référence de la charge utile des e-mails

Marketing vs transactionnel