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

# Transaktions-API

> Ereignisgesteuerte E-Mails aus Ihrer Anwendung senden. Anders als Kampagnen gehen Transaktions-E-Mails in Echtzeit an jeweils einen Kontakt, und Notifuse legt den Kontakt beim Versand an oder aktualisiert ihn. Sie eignen sich für Benachrichtigungen, die Ihre Nutzer auslösen, und für automatisierte Abläufe.

![Liste der Transaktionsbenachrichtigungen in der Konsole](https://www.notifuse.com/docs/assets/screenshots/transactional_api.png)

## Häufige Anwendungsfälle

```
- Password Reset
- Order Confirmation
- Welcome Email
- Account Deletion
- Purchase Receipt
- Shipping Notifications
- Account Verification
- Payment Confirmations
```

## Die wichtigsten Funktionen

### Automatische Kontaktverwaltung

- Das Objekt `contact` in der Anfrage legt den Kontakt vor dem Versand an oder aktualisiert seine Felder, sodass seine Daten aktuell bleiben.
- Vorlagendaten (`data`) werden nicht am Kontakt gespeichert. Ihre Schlüssel werden zu Vorlagenvariablen der obersten Ebene, und das gespeicherte Kontaktprofil steht unter `contact` bereit.

Um den Kontakt auf diese Weise zu aktualisieren, braucht es das Schreibrecht für Kontakte. Ohne dieses Recht legt ein Versand einen fehlenden Kontakt nur mit seiner E-Mail-Adresse an und ändert nie einen bestehenden (siehe [Berechtigungen](#permissions)).

### Anreicherung der Vorlagendaten

Wenn Sie eine Transaktions-E-Mail senden, geht Notifuse so vor:

1. Legt den Kontakt an oder aktualisiert ihn und sucht ihn dann anhand der E-Mail-Adresse in Ihrem Arbeitsbereich
2. Legt die Schlüssel von `data` auf die oberste Ebene der Vorlagenvariablen und das gespeicherte Profil des Kontakts unter `contact`
3. Rendert die Vorlage mit den vollständigen Kontaktdaten
4. Versendet die personalisierte E-Mail

**Beispiel**: Sendet Ihre API `"data": {"order_id": "12345"}` und enthält das Kontaktprofil `{"first_name": "John", "last_name": "Doe"}`, kann die Vorlage `{{ order_id }}` und `{{ contact.first_name }}` verwenden.

### Deduplizierung mit External ID

- Setzen Sie `external_id`, damit dieselbe Benachrichtigung nicht zweimal verschickt wird: Benachrichtigungen mit derselben `external_id` gehen nur einmal raus.
- Verwenden Sie Ihre eigenen eindeutigen Kennungen (Bestell-IDs, Ereignis-IDs usw.).

**Beispiel**: Mit `external_id: "order-12345"` wird die Bestellbestätigung nur einmal zugestellt, auch wenn Ihr System sie mehrfach sendet.

### Optionen für die Zustellung

Jeder Versand kann Folgendes festlegen:

- **Von Name**: überschreibt den Standard-Anzeigenamen des Absenders
- **Betreff**: überschreibt die Betreffzeile der Vorlage (unterstützt Liquid)
- **Antwort-an**: legt eigene Antwortadressen fest
- **CC**: fügt Empfänger in Kopie hinzu
- **BCC**: fügt Empfänger in Blindkopie hinzu
- **Anhänge**: hängt Dateien an die E-Mail an (PDFs, Bilder, Dokumente usw.)

### Tracking

Öffnungen und Klicks richten sich nach den Einstellungen des Arbeitsbereichs und der [Tracking-Einwilligung](https://www.notifuse.com/de/docs/features/email-tracking.md) des Kontakts. Ein `contact` in der Anfrage kann `tracking_opens_consent` und `tracking_clicks_consent` mitbringen; beide werden mit der Quelle `api` erfasst, sofern Sie nicht `tracking_consent_source` senden. Jede Benachrichtigung kann das Tracking außerdem abschalten:

- **Kein Öffnungs- oder Klick-Tracking, UTM-Parameter behalten** (`tracking_mode: "no_tracking"`)
- **Für diese Benachrichtigung deaktiviert** (`tracking_mode: "disabled"`): Links werden nie umgeschrieben und tragen keine Tracking- oder UTM-Parameter. Verwenden Sie diese Option für Links, die unverändert bleiben müssen, etwa Anmeldelinks

## Überwachung in der Konsole

Die Seite **Transaktional** listet Ihre Benachrichtigungen mit ihren Statistiken der letzten 7, 30 oder 60 Tage auf, den heutigen Tag eingeschlossen:

- **Summen**: versendete E-Mails, Zustellrate mit ihrer Veränderung gegenüber dem vorherigen Zeitraum, Öffnungs- und Klickraten der getrackten E-Mails, Fehlschläge und Bounces.
- **Eine Zeile pro Benachrichtigung**: ihre Vorlage, versendete E-Mails, Zustell-, Öffnungs- und Klickrate, Fehlschläge, Bounce-Rate und der Zeitpunkt des letzten erfolgreichen Versands. Eine Zustellrate unter 97 % und eine Bounce-Rate ab 2 % sind hervorgehoben. Sie können nach Name oder ID suchen.
- **Zeilenaktionen**: einen Test senden, den API-Befehl anzeigen und über das Menü die Benachrichtigung bearbeiten, ihre Vorlage in der Vorschau ansehen, die ID kopieren, ihre Nachrichten in den [Protokollen](https://www.notifuse.com/de/docs/features/logs.md) öffnen oder sie löschen.

Ein Klick auf eine Zeile öffnet die Detailansicht der Benachrichtigung, die einen eigenen Link zum Teilen hat. Sie zeigt dieselben Statistiken für diese Benachrichtigung, verknüpft mit den passenden Nachrichten in den Protokollen. Dazu kommen die Sendungen pro Tag, die letzten Sendungen (alle 30 Sekunden aktualisiert), eine Vorschau der Vorlage, ihre Tracking- und UTM-Einstellungen, der Standardabsender und der API-Aufruf in cURL, TypeScript und Python. **K** und **J** springen zur vorherigen oder nächsten Benachrichtigung.

Bei einem SMTP-Anbieter gibt es keine Zustell- und Bounce-Raten, da SMTP keine Zustellereignisse meldet. Für die Statistiken ist das Leserecht für den Nachrichtenverlauf nötig.

## API-Endpunkt

Senden Sie eine Transaktions-E-Mail mit einer POST-Anfrage:

### Anfrage

```bash
curl -X POST \
  "https://v3.notifuse.com/api/transactional.send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "pwd-reset-user123-20240101",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "2024-01-01T12:00:00Z"
    },
    "metadata": {
      "user_id": "12345",
      "trigger": "forgot_password",
      "source": "web_app"
    },
    "email_options": {
      "from_name": "Support Team",
      "subject": "Reset your password, {{ contact.first_name }}",
      "reply_to": "support@yourcompany.com",
      "cc": ["admin@yourcompany.com"],
      "bcc": ["logs@yourcompany.com"],
      "attachments": [
        {
          "filename": "reset-guide.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf"
        }
      ]
    }
  }
}'
```

### Parameter

| Parameter                    | Typ    | Pflicht | Beschreibung                                  |
| ---------------------------- | ------ | ------- | --------------------------------------------- |
| `workspace_id`               | string | Ja      | Kennung Ihres Arbeitsbereichs                 |
| `notification.id`            | string | Ja      | Kennung der Vorlage für die E-Mail            |
| `notification.external_id`   | string | Nein    | Eindeutige Kennung zur Deduplizierung         |
| `notification.channels`      | array  | Ja      | Muss "email" enthalten                        |
| `notification.contact`       | object | Ja      | Kontaktobjekt mit mindestens einem Feld email |
| `notification.data`          | object | Nein    | Vorlagenvariablen für den E-Mail-Inhalt       |
| `notification.metadata`      | object | Nein    | Tracking-Daten (in Vorlagen nicht verfügbar)  |
| `notification.email_options` | object | Nein    | Einstellungen für das E-Mail-Routing          |

### E-Mail-Optionen

| Parameter     | Typ    | Beschreibung                                                                                                                                                                                     |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sender_id`   | string | Sendet von diesem Absender der Integration für Transaktions-E-Mails statt vom Absender der Vorlage. Eine unbekannte ID wird mit 400 abgelehnt, bevor der Kontakt angelegt oder aktualisiert wird |
| `from_name`   | string | Überschreibt den Standard-Anzeigenamen des Absenders                                                                                                                                             |
| `subject`     | string | Überschreibt die Betreffzeile der Vorlage (unterstützt Liquid, max. 255)                                                                                                                         |
| `reply_to`    | string | Legt eine eigene Antwortadresse fest, anstelle der Antwortadresse der Vorlage                                                                                                                    |
| `cc`          | array  | Liste der Empfänger in Kopie                                                                                                                                                                     |
| `bcc`         | array  | Liste der Empfänger in Blindkopie                                                                                                                                                                |
| `attachments` | array  | Dateianhänge (max. 20 Dateien, 3 MB pro Datei, 10 MB insgesamt)                                                                                                                                  |

## Data und Metadata

### Vorlagenvariablen (`data`)

Das Objekt `data` enthält die Variablen, die Ihre E-Mail-Vorlagen verwenden können:

```json
{
  "data": {
    "order_id": "ORD-12345",
    "total": "$99.99",
    "discount_code": "WELCOME20"
  }
}
```

In Vorlagen stehen sie dann als `{{ order_id }}`, `{{ total }}`, `{{ discount_code }}` zur Verfügung.

### Tracking-Daten (`metadata`)

Das Objekt `metadata` speichert Informationen für Analysen und Tracking und ist in Vorlagen **nicht verfügbar**:

```json
{
  "metadata": {
    "campaign_id": "welcome-series",
    "source": "mobile_app",
    "user_segment": "premium"
  }
}
```

Verwenden Sie Metadaten für internes Tracking, Analysen und Reporting.

## E-Mail-Anhänge

Hängen Sie Rechnungen, Belege, Tickets oder andere Dokumente an Ihre Transaktions-E-Mails an. Anhänge werden im Speicher automatisch dedupliziert.

### Grenzen für Anhänge

- **Maximale Anzahl**: 20 Anhänge pro E-Mail
- **Dateigröße**: 3 MB pro Datei
- **Gesamtgröße**: 10 MB pro E-Mail
- **Unterstützte Formate**: alle Dateitypen (PDF, PNG, JPEG, DOCX usw.)

### Parameter für Anhänge

| Parameter      | Typ    | Pflicht | Beschreibung                                                                                                                                                       |
| -------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `filename`     | string | Ja      | Dateiname (max. 255 Zeichen)                                                                                                                                       |
| `content`      | string | Ja      | Base64-kodierter Dateiinhalt                                                                                                                                       |
| `content_type` | string | Nein    | MIME-Typ (z. B. "application/pdf"), wird automatisch erkannt, wenn er fehlt                                                                                        |
| `disposition`  | string | Nein    | "attachment" (Standard) oder "inline"                                                                                                                              |
| `content_id`   | string | Nein    | Content-ID für Inline-Anhänge, im HTML-Inhalt als `<img src="cid:...">` referenziert. Nur erlaubt, wenn `disposition` "inline" ist. Fehlt sie, gilt der Dateiname. |

### Beispiel mit PDF-Rechnung

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "contact": {
      "email": "customer@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99"
    },
    "email_options": {
      "attachments": [
        {
          "filename": "invoice-12345.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf",
          "disposition": "attachment"
        }
      ]
    }
  }
}
```

### Beispiel mit mehreren Anhängen

```json
{
  "email_options": {
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjQKJeLjz9MK...",
        "content_type": "application/pdf"
      },
      {
        "filename": "receipt.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png"
      },
      {
        "filename": "terms.docx",
        "content": "UEsDBBQABgAIAAAAIQ...",
        "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      }
    ]
  }
}
```

### Inline-Bilder (Content-ID)

Betten Sie Bilder pro Empfänger, etwa QR-Codes oder personalisierte Grafiken, direkt in den E-Mail-Inhalt ein, statt sie unter einer URL zu hosten. Setzen Sie `disposition` auf `"inline"`, geben Sie dem Anhang eine `content_id` und referenzieren Sie ihn im HTML Ihrer Vorlage als `<img src="cid:...">`:

```json
{
  "email_options": {
    "attachments": [
      {
        "filename": "check-in-qr.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png",
        "disposition": "inline",
        "content_id": "checkInQr"
      }
    ]
  }
}
```

Und in der E-Mail-Vorlage:

```html
<img src="cid:checkInQr" alt="Your check-in QR code" />
```

Hinweise:

- `content_id` darf nur Buchstaben, Ziffern und die Zeichen `.` `_` `-` `@` enthalten (max. 255 Zeichen) und wird nur akzeptiert, wenn `disposition` `"inline"` ist.
- Fehlt `content_id`, dient der Dateiname als Content-ID, sodass auch `<img src="cid:check-in-qr.png">` funktioniert.
- Inline-Bilder werden in einem MIME-Teil `multipart/related` neben dem HTML-Inhalt zugestellt, sodass E-Mail-Programme sie im Inhalt anzeigen und nicht als herunterladbare Anhänge.
- Da das Bild im Nachrichteninhalt mitreist, rufen Link-Proxys und Bild-Caching-Dienste es nie ab und protokollieren es auch nicht. Das passt zu empfängerspezifischen Geheimnissen wie QR-Codes.
- Bei Mailgun wird die `content_id` auch zum Dateinamen des zugestellten Teils. Wählen Sie beim Versand über Mailgun daher eine `content_id` mit Dateiendung (z. B. `checkInQr.png`).

### Häufige Anwendungsfälle

- **Bestellbestätigungen**: Rechnungen und Belege anhängen
- **Buchungsbestätigungen**: Tickets und Reisepläne anhängen
- **Rechtsdokumente**: Verträge und Vereinbarungen anhängen
- **Berichte**: Analyseberichte und Zusammenfassungen anhängen
- **Zertifikate**: Abschlusszertifikate und Badges anhängen
- **Veranstaltungstickets**: QR-Codes pro Empfänger als Inline-Bilder einbetten

## SMTP-Bridge

Notifuse hat einen eingebauten SMTP-Bridge-Server, sodass Sie Transaktions-E-Mails aus gewöhnlichen SMTP-Clients senden können, statt die HTTP-API aufzurufen. Er eignet sich für:

- **Altsysteme**: Anbindung bestehender Anwendungen, die nur SMTP unterstützen
- **E-Mail-Bibliotheken**: Nutzung gängiger E-Mail-Bibliotheken in jeder Programmiersprache
- **Framework-Integration**: Arbeit mit Frameworks, die SMTP von Haus aus unterstützen
- **Schrittweise Migration**: Wechsel von bestehenden E-Mail-Anbietern, ohne den Anwendungscode zu ändern

### So funktioniert es

Der SMTP-Bridge-Server nimmt E-Mails auf Port 587 (STARTTLS) oder 465 (implizites TLS) an. Der Inhalt der E-Mail muss eine JSON-Nutzlast im Format der Transaktions-API enthalten, und Sie authentifizieren sich mit den API-Zugangsdaten Ihres Arbeitsbereichs.

### E-Mails über SMTP senden

#### Authentifizierung

- **Benutzername**: die API-E-Mail-Adresse Ihres Arbeitsbereichs (die E-Mail-Adresse, die zu Ihrem API-Schlüssel gehört)
- **Passwort**: der API-Schlüssel Ihres Arbeitsbereichs
- **Sicherheit**: STARTTLS (Port 587) oder implizites TLS / SMTPS (Port 465), je nach Ihrer Einstellung `SMTP_BRIDGE_TLS`
- **Server**: der Host Ihrer konfigurierten SMTP-Bridge (z. B. `smtp.yourdomain.com`)

#### E-Mail-Format

Der Inhalt der E-Mail muss eine JSON-Nutzlast im Format der Transaktions-API sein:

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "unique-id-123",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "1 hour"
    }
  }
}
```

## Berechtigungen

Das Schreibrecht für **Transaktional** reicht allein zum Senden aus, über die API wie über die SMTP-Bridge. Ein API-Schlüssel nur zum Senden ist deshalb praktikabel: Geben Sie einem Schlüssel das Schreibrecht für Transaktional und sonst nichts, dann kann er E-Mails senden, ohne einen einzigen Kontakt zu lesen oder zu bearbeiten. Siehe [Admins & API-Schlüssel](https://www.notifuse.com/de/docs/features/admins-api-keys.md).

Für einen so eng gefassten Schlüssel gelten zwei Einschränkungen, auf der SMTP-Bridge wie in der API:

- **Ohne Schreibrecht für Kontakte** legt ein Versand den Kontakt des Empfängers zwar an, wenn er noch nicht existiert, speichert aber nur seine E-Mail-Adresse. Alle anderen Felder des Objekts `contact` werden verworfen, und ein bestehender Kontakt wird nie geändert.
- **Ohne Leserecht für Kontakte** wird ein Versand mit `cc` oder `bcc` abgelehnt. Auf der SMTP-Bridge stammen `cc` und `bcc` aus den Headern `Cc:` und `Bcc:` der Nachricht, sodass ein reiner Sende-Zugang, der sie setzt, schon bei der Übergabe der Nachricht abgewiesen wird.

Geben Sie dem Schlüssel Lese- und Schreibrecht für Kontakte, wenn er beim Senden Kontaktprofile anreichern oder zusätzliche Empfänger in Kopie setzen soll. Mit beiden Rechten verhält sich der Schlüssel wie bisher.

Das Schreibrecht für Transaktional deckt jeden Weg ab, auf dem über die Zugangsdaten Ihres Anbieters echte E-Mails verschickt werden: `/api/transactional.send`, `/api/transactional.testTemplate` und die SMTP-Bridge. Das Testen eines E-Mail-Anbieters (`/api/email.testProvider`) ist dem Inhaber des Arbeitsbereichs vorbehalten, ein API-Schlüssel kann es also nicht aufrufen. Eine Test-E-Mail braucht außerdem das Leserecht für Vorlagen und, wenn sie für eine Verteilerliste verschickt wird (`list_id`), das Leserecht für Listen.

Das Recht **Gelesen** für Transaktional deckt nur die Definitionen der Benachrichtigungen ab (sie auflisten und eine öffnen). Senden kann ein Schlüssel damit nicht.

## Vorlagenintegration

### Datenstruktur in Vorlagen

Ihre Vorlagen können sowohl die API-Daten als auch das Kontaktprofil verwenden:

```liquid
<!-- From API data -->
Hello! Your order #{{ order_id }} has been confirmed.

<!-- From contact profile (automatically enriched) -->
Dear {{ contact.first_name }} {{ contact.last_name }},

<!-- Combining both -->
We've sent your order #{{ order_id }} to {{ contact.email }}.
```

### Bedingte Blöcke

Blöcke einer visuellen Vorlage lassen sich nur dann verschicken, wenn eine Bedingung auf diese Daten zutrifft, etwa ein Abschnitt, der nur erscheint, wenn `order.total` größer als 100 ist. Siehe [Bedingte Blöcke](https://www.notifuse.com/de/docs/features/templates.md#conditional-blocks).

### Vollständiges Beispiel

**API-Anfrage**:

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "external_id": "order-12345-confirmation",
    "contact": {
      "email": "sarah@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99",
      "items": ["Product A", "Product B"]
    },
    "metadata": {
      "campaign_id": "order-confirmations",
      "source": "checkout"
    }
  }
}
```

**Bestehendes Kontaktprofil**:

```json
{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah@example.com",
  "phone": "+1234567890"
}
```

**In der Vorlage verfügbar**:

```liquid
Hi {{ contact.first_name }}!

Your order #{{ order_id }} totaling {{ total }} has been confirmed.

Items:
{% for item in items %}
- {{ item }}
{% endfor %}

We'll send updates to {{ contact.email }}.
```

## API-Referenz

## Beispiele für die Deduplizierung

### Bestellbestätigungen

```json
{
  "external_id": "order-12345-confirmation"
}
```

### Passwort-Zurücksetzungen

```json
{
  "external_id": "pwd-reset-user123-20240101"
}
```

### Willkommens-E-Mails

```json
{
  "external_id": "welcome-user123"
}
```

Einheitliche Muster für `external_id` verhindern doppelte Benachrichtigungen, auch wenn Ihre Anwendung mehrere Anfragen sendet.

Die vollständige API-Dokumentation und weitere Parameter finden Sie in der [API-Referenz](https://www.notifuse.com/docs/api-reference/send-a-transactional-notification.md).
