SMTP-Gateway

Das SMTP-Gateway akzeptiert die standardmäßige E-Mail-Übermittlung und leitet jede Nachricht als transaktionale E-Mail an Messaging API v2 Notify weiter. Verwenden Sie es, wenn ein bestehendes E-Mail-Tool – ein MTA, ein Framework-Mailer, ein SDK – einfacher anzubinden ist als eine JSON-Anfrage an die API.

Hinweis

Das Gateway ist nur für transaktionale E-Mails vorgesehen. Für Audience-Segmente, Zeitplanung oder A/B-Kampagnen rufen Sie Notify direkt auf.

Wie es funktioniert

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

1. Der Client verbindet sich mit smtp.pushwoosh.com auf Port 587, stuft die Verbindung mit STARTTLS auf TLS hoch und authentifiziert sich dann mit AUTH PLAIN.
2. Das Gateway parst die MIME-Nachricht und erstellt eine Notify-Anfrage mit platforms: ["EMAIL"] und message_type: TRANSACTIONAL.
3. Das API-Token von AUTH PLAIN wird als Authorization-Header an die Messaging API weitergeleitet. Die Token-Validierung, der Anwendungsabgleich, die Sendeidentität und die Bounce-Verwaltung erfolgen alle auf der API-Seite.

Endpunkt

Einstellung	Wert
Host	smtp.pushwoosh.com
Port	587 (SMTP-Übermittlung)
TLS	STARTTLS – obligatorisch vor AUTH
Auth	AUTH PLAIN

Authentifizierung

AUTH PLAIN verwendet zwei Pushwoosh-Anmeldeinformationen.

AUTH-Feld	Pushwoosh-Wert
username	Anwendungscode, zum Beispiel XXXXX-XXXXX
password	Server-API-Token

AUTH wird außerhalb von TLS abgelehnt. Das Token erscheint niemals in der Nachricht – es wird nur zur Autorisierung des Upstream-Notify-Aufrufs verwendet.

Wie Nachrichten auf Notify abgebildet werden

MIME- oder SMTP-Feld	Notify-Feld
RCPT TO	target.users.list – Pushwoosh löst diese Adressen zu Abonnenten auf
AUTH username	application
Subject:-Header	email_payload.subject["default"] (RFC 2047 dekodiert)
From:-Header	email_payload.from – name und email
HTML-Teil	email_payload.body (bevorzugt, wenn beide Teile vorhanden sind)
Nur-Text-Teil	email_payload.body (wird verwendet, wenn HTML fehlt)
MAIL FROM	Ignoriert – Pushwoosh ersetzt seine eigene Sendeidentität und verwaltet Bounces selbst

Jede Nachricht wird mit schedule.send_date: now gesendet.

Limits

Limit	Wert
Maximale Nachrichtengröße	25 MiB
Maximale Empfänger pro Umschlag (RCPT TO)	50

Fehlerzuordnung

gRPC-Statuscodes, die von der Messaging API zurückgegeben werden, werden in standardmäßige SMTP-Antwortcodes übersetzt, damit jeder SMTP-Client einen aussagekräftigen Fehler anzeigt.

Upstream-gRPC-Status	SMTP-Antwort	Bedeutung
Unauthenticated	535 5.7.8	Ungültiger Anwendungscode oder API-Token.
PermissionDenied	550 5.7.1	Das Token hat keine Rechte für diese Anwendung.
InvalidArgument / FailedPrecondition / OutOfRange	550 5.6.0	Ungültiger MIME-Inhalt (z. B. fehlender Betreff oder Text).
NotFound	550 5.1.1	Anwendung oder Empfänger wurde nicht gefunden.
ResourceExhausted	452 4.5.3	Ratenlimit erreicht – versuchen Sie es später erneut.
DeadlineExceeded / Unavailable	451 4.4.1	Vorübergehender Upstream-Fehler – versuchen Sie es später erneut.
any other failure	451 4.5.0	Vorübergehender interner Fehler – versuchen Sie es später erneut.

Codes im 4xx-Bereich sind temporär und sollten vom Client erneut versucht werden; Codes im 5xx-Bereich sind permanent und erfordern eine clientseitige Korrektur.

Beispiel: Senden mit 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"

Der From:-Header im MIME-Body ist das, was Pushwoosh erreicht – der --from-Umschlag (MAIL FROM) wird verworfen.

Anmerkungen

• Das Gateway ist zustandslos und speichert keine Nachrichten. Nach der Weiterleitung liegt die Zustellung in der Verantwortung der Messaging API.
• Bounces, Beschwerden und Abmeldelinks werden von Pushwoosh genauso wie bei jeder anderen transaktionalen E-Mail behandelt.
• Für den Kampagnenversand (Segmente, Zeitplanung, A/B) verwenden Sie Notify direkt – das SMTP-Gateway ist nur für die Übermittlung vorgesehen.

Siehe auch

Übersicht über die Messaging API v2

Notify

Referenz zur E-Mail-Payload

Marketing vs. transaktional