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

<Aside type="note">
Das Gateway ist nur für transaktionale E-Mails vorgesehen. Für Audience-Segmente, Zeitplanung oder A/B-Kampagnen rufen Sie [`Notify`](/de/developer/api-reference/messaging-api-v2/notify/) direkt auf.
</Aside>

## 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 <div style="width:140px"></div> | Wert <div style="width:340px"></div> |
|---------|-------|
| 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 <div style="width:120px"></div> | Pushwoosh-Wert |
|------------|-----------------|
| `username` | [Anwendungscode](/de/developer/api-reference/api-identifiers/#application-code), zum Beispiel `XXXXX-XXXXX` |
| `password` | [Server-API-Token](/de/developer/api-reference/api-access-token/#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 <div style="width:200px"></div> | 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 <div style="width:280px"></div> | 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 <div style="width:280px"></div> | SMTP-Antwort <div style="width:120px"></div> | 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

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

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`](/de/developer/api-reference/messaging-api-v2/notify/) direkt – das SMTP-Gateway ist nur für die Übermittlung vorgesehen.

## Siehe auch

<CardGrid>
  <LinkCard title="Übersicht über die Messaging API v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Referenz zur E-Mail-Payload" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="Marketing vs. transaktional" href="/product/messaging-channels/marketing-vs-transactional/" />
</CardGrid>