> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 }}`.

```liquid
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](https://www.notifuse.com/de/docs/features/templates.md).

### 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](https://www.notifuse.com/docs/assets/screenshots/transactional_notification_edit.png)

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**

```bash
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**

```javascript
// 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**

```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
<?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**

```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](https://www.notifuse.com/de/docs/features/transactional-api.md#permissions).

## 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](https://www.notifuse.com/de/docs/features/logs.md).

![Eine in den Protokollen geöffnete Nachricht mit ihren Zustellereignissen und den Daten, mit denen sie gesendet wurde](https://www.notifuse.com/docs/assets/screenshots/logs_message_detail.png)

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

- [Transaktions-API](https://www.notifuse.com/de/docs/features/transactional-api.md) beschreibt alle Felder der Anfrage, auch `email_options` für Reply-To, CC, BCC und Anhänge.
- [Eine Willkommenssequenz aufbauen](https://www.notifuse.com/de/docs/guides/welcome-sequence.md) für E-Mails nach einer Registrierung.
- [Webhooks](https://www.notifuse.com/de/docs/features/webhooks.md), um Zustell- und Bounce-Ereignisse in Ihrer App zu empfangen.
