Zum Inhalt springen

Produkt-E-Mails

E-Mails zum Zurücksetzen des Passworts aus Ihrer App senden

Legen Sie eine Transaktionsbenachrichtigung für Passwort-Resets an und senden Sie sie mit einem einzigen API-Aufruf aus Ihrem Backend.

Wenn ein Nutzer sein Passwort zurücksetzen möchte, ruft Ihre App die Notifuse-API auf. Notifuse schickt ihm dann eine E-Mail mit dem Reset-Link, den Ihre App erzeugt hat.

Bevor Sie beginnen

  • Ein Arbeitsbereich, in dem unter Einstellungen › Integrationen ein E-Mail-Anbieter für Transaktionale E-Mails festgelegt ist. Fehlt er, warnt die Seite Transaktional, dass keine Benachrichtigungen gesendet werden können.
  • Ein Backend, das den Reset-Link erzeugt (Token, Ablaufzeit, die Seite, die ihn prüft). Notifuse stellt nur den Link zu.
  • Ihre Arbeitsbereich-ID. Das ist die ID, die Sie beim Anlegen des Arbeitsbereichs gewählt haben. Sie steht in der URL der Konsole nach /console/workspace/.
  • Die Adresse Ihrer Notifuse-Instanz, also dieselbe, unter der Sie die Konsole öffnen. Die Beispiele verwenden https://YOUR_NOTIFUSE_HOST.
  1. E-Mail-Vorlage erstellen

    Öffnen Sie Vorlagen, klicken Sie auf Neue Vorlage und wählen Sie in der Galerie das Modell Passwort zurücksetzen. Es enthält bereits einen Button und den Link als Klartext, beide zeigen auf {{ reset_url }}.

    Sie können auch mit einer leeren Vorlage beginnen. Setzen Sie dann ihre Kategorie auf Transaktional, denn eine Benachrichtigung bietet nur Vorlagen dieser Kategorie an.

    Die Vorlage kann zwei Arten von Variablen verwenden:

    • Die Schlüssel, die Sie in data senden, liegen auf oberster Ebene. Schreiben Sie {{ reset_url }}, nicht {{ data.reset_url }}.
    • Der Kontakt liegt unter contact, zum Beispiel {{ contact.first_name }} oder {{ contact.email }}.
    Hi {{ contact.first_name }},
    
    <a href="{{ reset_url }}">Choose a new password</a>

    Legen Sie in den Einstellungen der Vorlage Betreff und Absender fest und speichern Sie. Den Editor und die Testdaten der Vorschau beschreibt Vorlagen.

  2. Transaktionsbenachrichtigung erstellen

    Öffnen Sie Transaktional und klicken Sie auf Neue Benachrichtigung. Füllen Sie aus:

    • Name: der Name, den Sie in der Konsole sehen, zum Beispiel „Passwort-Reset-E-Mail“.
    • API-Bezeichner: der Wert, den Ihr Code sendet, zum Beispiel password_reset. Nur Kleinbuchstaben, Ziffern und Unterstriche, höchstens 32 Zeichen. Nach dem Anlegen der Benachrichtigung lässt er sich nicht mehr ändern.
    • E-Mail-Vorlage: die Vorlage aus Schritt 1.

    Klicken Sie auf Benachrichtigung erstellen.

    Eine Transaktionsbenachrichtigung: ihr Name, der feste API-Bezeichner password_reset und ihre E-Mail-Vorlage
    Eine Transaktionsbenachrichtigung: ihr Name, der feste API-Bezeichner password_reset und ihre E-Mail-Vorlage

    Auf der Seite der Benachrichtigung zeigt der Bereich API-Aufruf eine fertige Anfrage in cURL, TypeScript und Python. Unter Alle Sprachen finden Sie weitere.

  3. API-Schlüssel erstellen

    Gehen Sie zu Einstellungen › Team & API-Schlüssel und klicken Sie auf API-Schlüssel erstellen. Füllen Sie API-Schlüssel-Name aus, etwa „Backend Passwort-Reset“.

    Unter Berechtigungen genügt Schreibzugriff auf Transaktional, um zu senden. Ein Schlüssel ohne weitere Rechte kann E-Mails senden, Ihre Kontakte aber weder lesen noch bearbeiten. Meldet die Konsole, dass benutzerdefinierte Berechtigungen eine Notifuse-Studio-Lizenz erfordern, kann der Schlüssel nur Vollzugriff haben. Für diese Anleitung funktioniert er genauso.

    Klicken Sie auf API-Schlüssel erstellen und kopieren Sie das Token sofort: Es wird nur einmal angezeigt und lässt sich später nicht mehr abrufen. Speichern Sie es bei den Secrets Ihres Backends, niemals im Browser-Code.

  4. E-Mail aus dem Backend senden

    Rufen Sie POST /api/transactional.send mit dem Token als Bearer-Token auf. Der Body braucht:

    • workspace_id: Ihre Arbeitsbereich-ID.
    • notification.id: den API-Bezeichner, password_reset.
    • notification.channels: ["email"]. Mindestens ein Kanal ist Pflicht.
    • notification.contact: den Empfänger, mindestens mit einer gültigen email.
    • notification.data: die Vorlagenvariablen, hier reset_url.
    • notification.external_id (optional): Ihre eigene ID für diesen Versand, mit der sich Duplikate vermeiden lassen. Mehr dazu im nächsten Abschnitt.

    cURL

    curl -X POST "https://YOUR_NOTIFUSE_HOST/api/transactional.send" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workspace_id": "YOUR_WORKSPACE_ID",
        "notification": {
          "id": "password_reset",
          "external_id": "pwd-reset-u123-1700000000",
          "channels": ["email"],
          "contact": {
            "email": "user@example.com",
            "first_name": "Ada"
          },
          "data": {
            "reset_url": "https://app.example.com/reset?token=abc123"
          }
        }
      }'

    Node.js

    // Node.js 18 or later (built-in fetch)
    async function sendPasswordReset(user, resetRequestId, resetUrl) {
      const response = await fetch('https://YOUR_NOTIFUSE_HOST/api/transactional.send', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.NOTIFUSE_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          workspace_id: 'YOUR_WORKSPACE_ID',
          notification: {
            id: 'password_reset',
            external_id: `pwd-reset-${user.id}-${resetRequestId}`,
            channels: ['email'],
            contact: { email: user.email, first_name: user.firstName },
            data: { reset_url: resetUrl }
          }
        })
      })
    
      const result = await response.json()
      if (!response.ok) {
        throw new Error(`Notifuse error ${response.status}: ${result.error}`)
      }
      return result.message_id
    }

    Python

    import os
    import requests
    
    def send_password_reset(user, reset_request_id, reset_url):
        response = requests.post(
            "https://YOUR_NOTIFUSE_HOST/api/transactional.send",
            headers={"Authorization": f"Bearer {os.environ['NOTIFUSE_API_KEY']}"},
            json={
                "workspace_id": "YOUR_WORKSPACE_ID",
                "notification": {
                    "id": "password_reset",
                    "external_id": f"pwd-reset-{user['id']}-{reset_request_id}",
                    "channels": ["email"],
                    "contact": {"email": user["email"], "first_name": user["first_name"]},
                    "data": {"reset_url": reset_url},
                },
            },
            timeout=10,
        )
        result = response.json()
        if not response.ok:
            raise RuntimeError(f"Notifuse error {response.status_code}: {result.get('error')}")
        return result["message_id"]

    PHP

    <?php
    function sendPasswordReset(array $user, string $resetRequestId, string $resetUrl): string
    {
        $payload = [
            'workspace_id' => 'YOUR_WORKSPACE_ID',
            'notification' => [
                'id' => 'password_reset',
                'external_id' => "pwd-reset-{$user['id']}-{$resetRequestId}",
                'channels' => ['email'],
                'contact' => ['email' => $user['email'], 'first_name' => $user['first_name']],
                'data' => ['reset_url' => $resetUrl],
            ],
        ];
    
        $ch = curl_init('https://YOUR_NOTIFUSE_HOST/api/transactional.send');
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . getenv('NOTIFUSE_API_KEY'),
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode($payload),
            CURLOPT_TIMEOUT => 10,
        ]);
        $body = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
    
        $result = json_decode($body, true);
        if ($status !== 200) {
            throw new RuntimeException("Notifuse error {$status}: " . ($result['error'] ?? $body));
        }
        return $result['message_id'];
    }

    Go

    package notify
    
    import (
    	"bytes"
    	"encoding/json"
    	"fmt"
    	"net/http"
    	"os"
    	"time"
    )
    
    func SendPasswordReset(userID, email, firstName, resetRequestID, resetURL string) (string, error) {
    	payload := map[string]any{
    		"workspace_id": "YOUR_WORKSPACE_ID",
    		"notification": map[string]any{
    			"id":          "password_reset",
    			"external_id": fmt.Sprintf("pwd-reset-%s-%s", userID, resetRequestID),
    			"channels":    []string{"email"},
    			"contact":     map[string]string{"email": email, "first_name": firstName},
    			"data":        map[string]string{"reset_url": resetURL},
    		},
    	}
    	body, err := json.Marshal(payload)
    	if err != nil {
    		return "", err
    	}
    
    	req, err := http.NewRequest(http.MethodPost, "https://YOUR_NOTIFUSE_HOST/api/transactional.send", bytes.NewReader(body))
    	if err != nil {
    		return "", err
    	}
    	req.Header.Set("Authorization", "Bearer "+os.Getenv("NOTIFUSE_API_KEY"))
    	req.Header.Set("Content-Type", "application/json")
    
    	client := &http.Client{Timeout: 10 * time.Second}
    	resp, err := client.Do(req)
    	if err != nil {
    		return "", err
    	}
    	defer resp.Body.Close()
    
    	var result struct {
    		MessageID string `json:"message_id"`
    		Error     string `json:"error"`
    	}
    	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
    		return "", err
    	}
    	if resp.StatusCode != http.StatusOK {
    		return "", fmt.Errorf("notifuse error %d: %s", resp.StatusCode, result.Error)
    	}
    	return result.MessageID, nil
    }

    Ein erfolgreicher Aufruf liefert 200 mit {"message_id": "…", "success": true}. Bei einem Fehler kommt ein JSON-Body mit einem Feld error zurück, zum Beispiel 400 bei einem fehlenden Feld oder einem unbekannten API-Bezeichner und 500, wenn der Versand beim Anbieter scheitert.

Doppelte E-Mails mit external_id vermeiden

Gibt es im Arbeitsbereich bereits eine Nachricht mit derselben external_id, sendet Notifuse nichts und gibt die message_id der ersten Nachricht zurück. Ihr Code kann also einen Aufruf nach einem Timeout wiederholen, ohne dass der Nutzer zwei E-Mails erhält.

Verwenden Sie eine external_id pro Reset-Anfrage, zum Beispiel die Nutzer-ID plus die ID oder den Erstellungszeitpunkt des Reset-Tokens. Fordert der Nutzer später einen neuen Link an, braucht die neue Anfrage eine neue external_id. Sonst ist der Aufruf erfolgreich, aber es geht keine E-Mail hinaus.

Kontaktfelder und ein Schlüssel nur zum Senden

Notifuse legt den Kontakt an, wenn die E-Mail-Adresse noch nicht im Arbeitsbereich existiert. Mit einem Schlüssel, der nur Schreibzugriff auf Transaktional hat, gilt:

  • Ein neuer Kontakt wird nur mit der E-Mail-Adresse gespeichert. Die übrigen Felder, die Sie senden, etwa first_name, werden verworfen. {{ contact.first_name }} bleibt in dieser ersten E-Mail daher leer.
  • Ein bestehender Kontakt wird nie geändert, und die Vorlage verwendet die bereits gespeicherten Felder.

Soll die E-Mail den Nutzer mit Namen begrüßen, geben Sie dem Schlüssel zusätzlich Schreibzugriff auf Kontakte. Oder Sie senden den Namen in data und schreiben {{ first_name }} in die Vorlage. Siehe Transaktions-API.

Prüfen, ob es funktioniert

Lösen Sie in Ihrer App einen Reset für Ihre eigene Adresse aus, oder führen Sie das cURL-Beispiel mit dieser Adresse aus.

Öffnen Sie Protokolle, bleiben Sie auf dem Tab Nachrichten und suchen Sie nach Ihrer E-Mail-Adresse oder der gesendeten external_id. Als Herkunft sollte die Nachricht Transaktional zeigen. Ein Klick darauf zeigt ihre Ereignisse (gesendet, zugestellt, geöffnet) und unter Daten die reset_url, mit der sie verschickt wurde. Siehe Protokolle.

Eine in den Protokollen geöffnete Nachricht mit ihren Zustellereignissen und den Daten, mit denen sie gesendet wurde
Eine in den Protokollen geöffnete Nachricht mit ihren Zustellereignissen und den Daten, mit denen sie gesendet wurde

Senden Sie dieselbe Anfrage ein zweites Mal: Die Antwort enthält dieselbe message_id, und in Protokolle erscheint keine zweite E-Mail.

Nächste Schritte