Transaktionale E-Mails einrichten

Transaktionale E-Mails werden durch eine Benutzeraktion ausgelöst — ein Passwort-Reset, eine Bestellbestätigung, eine Willkommensnachricht nach der Registrierung. Anders als Marketing-Kampagnen gehen sie an einen einzelnen Empfänger zu einem bestimmten Zeitpunkt, und die Empfänger erwarten sie sofort. Diese Anleitung führt durch das Erstellen einer transaktionalen E-Mail, das Erzeugen eines API-Keys und den Versand aus Ihrer Anwendung.

Für den konzeptionellen Überblick (transaktional vs. Marketing, Slugs, Anhänge, Monitoring) siehe Transaktionale E-Mails. Diese Seite konzentriert sich auf die Integrationsschritte.

Häufige Beispiele:

• Links zum Zurücksetzen des Passworts
• Willkommens-E-Mails nach der Registrierung
• Bestellbestätigungen und Belege
• Versandbenachrichtigungen
• E-Mails zur Kontoverifizierung

Eine transaktionale E-Mail erstellen

Transaktionale E-Mails sind eine eigenständige Entität, getrennt von Marketing-Vorlagen — jede hat einen eindeutigen Slug, den Ihre Anwendung beim Versand referenziert.

Einen API-Key erzeugen

Für transaktionale Sendevorgänge benötigen Sie einen API-Key zur Authentifizierung.

Versand über das TypeScript-SDK

Installieren Sie das Owlat-SDK und versenden Sie Ihre erste transaktionale E-Mail:

import { Owlat } from '@owlat/sdk-js'

const owlat = new Owlat('lm_live_...')

const result = await owlat.transactional.send({
  email: 'user@example.com',
  slug: 'order-confirmation',
  dataVariables: {
    orderNumber: '#12345',
    customerName: 'Jane',
    total: '$49.99',
  },
})

// result.transactionalEmailId — the send-record id, use it to track delivery

Das SDK übernimmt Authentifizierung, Serialisierung und Fehlerbehandlung für Sie. Übergeben Sie im Objekt dataVariables alle Datenvariablen, die Ihre E-Mail erwartet. Sie können eine E-Mail über slug oder über transactionalId adressieren.

Versand über das Java-SDK

Owlat owlat = new Owlat("lm_live_...");

owlat.transactional().send(
    SendTransactionalParams.builder("user@example.com")
        .slug("order-confirmation")
        .dataVariables(Map.of(
            "orderNumber", "#12345",
            "customerName", "Jane",
            "total", "$49.99"
        ))
        .build()
);

Der Builder nimmt die Empfängeradresse als einziges Positionsargument entgegen; den Slug setzen Sie mit .slug(...) und alle Variablen übergeben Sie auf einmal mit .dataVariables(Map).

Versand über cURL

Wenn Sie die API lieber direkt aufrufen:

curl -X POST https://your-deployment.convex.site/api/v1/transactional \
  -H "Authorization: Bearer lm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "order-confirmation",
    "email": "user@example.com",
    "dataVariables": {
      "orderNumber": "#12345",
      "customerName": "Jane",
      "total": "$49.99"
    }
  }'

Eine erfolgreiche Anfrage liefert den Status 202 Accepted — die E-Mail wird zur Zustellung eingereiht, nicht synchron versendet. Der Response-Body enthält:

API-Code im Dashboard ansehen

Sie müssen den Aufruf nicht von Hand schreiben. In der Liste Transaktional hat jede E-Mail die Aktion API-Code anzeigen (das Symbol < >, ebenfalls im Menü der Zeile), die einen fertigen Sende-Codeausschnitt in cURL, JavaScript und Python öffnet — bereits mit dem Slug der E-Mail vorbelegt. Kopieren, Ihren API-Key einsetzen, und schon versenden Sie.

Fehlerbehandlung

Schlägt ein transaktionaler Versand fehl, gibt die API einen der unten aufgeführten kategorisierten Status zurück. Richten Sie Ihre Retry-Logik am Statuscode aus, nicht am Meldungstext.

Bei den Fehlern 429 und 500 sollten Sie in Ihrer Retry-Logik einen exponentiellen Backoff implementieren. Transaktionale E-Mails sind wichtig für Ihre Benutzer — bauen Sie daher Resilienz in Ihren Sendecode ein.

Nächste Schritte

• Transactional API — vollständige Endpunkt- und Feldreferenz
• TypeScript-SDK — komplette SDK-Referenz
• Java-SDK — Referenz zum Java-SDK
• Webhooks — lassen Sie sich in Echtzeit über Zustellereignisse benachrichtigen