Zum Inhalt springen

Transaktionsmails per API

Bestellbestätigungen und Passwort-Links per POST /api/v1/transactional/send versenden, mit Vorlage per Slug, Variablen und Idempotenz-Key.

Bestellbestätigungen, Passwort-Links oder Rechnungen versenden Sie über dieselben Absender-Konten wie Ihre Newsletter, mit Zustell- und Klick-Tracking.

Vorlage anlegen

Legen Sie unter Vorlagen eine neue Vorlage vom Typ Transaktion (API) an und vergeben Sie einen Slug, zum Beispiel order-confirmation. Erlaubt sind Kleinbuchstaben, Zahlen und Bindestriche. Im Betreff und im Inhalt nutzen Sie Variablen als Platzhalter, etwa {{order.number}}.

Senden

Sie brauchen einen API-Key mit der Berechtigung transactional:send.

curl -X POST https://app.example.com/api/v1/transactional/send \
  -H "Authorization: Bearer nl_…" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "order-confirmation",
    "to": "kunde@example.com",
    "variables": { "first_name": "Max", "order": { "number": "10023", "total": "49,90 €" } },
    "idempotencyKey": "order-10023"
  }'

Die Felder

  • template (Pflicht): Slug oder ID der Vorlage.
  • to (Pflicht): Empfängeradresse.
  • variables: beliebige Werte für die Platzhalter, auch verschachtelt.
  • senderId: ein bestimmtes Absender-Konto. Ohne Angabe wählt die App automatisch.
  • replyTo: abweichende Antwortadresse.
  • track: { "opens": false, "clicks": true } ist der Standard.
  • idempotencyKey: höchstens 120 Zeichen. Derselbe Key innerhalb von 24 Stunden sendet nicht erneut, sondern liefert die erste Nachricht mit "duplicate": true zurück.

Die Antwort enthält ok, messageId und status. Schlägt der Versand fehl, kommt zusätzlich error mit.

Der Idempotenz-Key steht im JSON-Body, nicht in einem Header. Nutzen Sie eine eindeutige Kennung aus Ihrem System, etwa die Bestellnummer. So gehen bei Wiederholungen keine doppelten Mails raus.

Sperrliste

Abmeldungen vom Newsletter gelten für Transaktionsmails nicht. Harte Bounces und Spam-Beschwerden schon: An solche Adressen sendet die App nicht und antwortet mit Status 422 und dem Code suppressed.

Testen und nachverfolgen

Unter Transaktionsmails senden Sie eine Testmail mit Vorlage, Empfänger und Variablen als JSON. Darunter listet die App die letzten Einzelmails mit Status und Fehlern. Per MCP steht dafür das Tool transactional_send bereit.

Weiter: Webhooks