# Idempotenz

> E-Mail-Sendungen mit dem Header Idempotency-Key sicher wiederholen. Welche Endpunkte ihn unterstützen, Format und Geltungsbereich des Schlüssels, das 24-Stunden-Fenster für Wiederholungen und die zugehörigen Fehler.

Bei Netzwerkfehlern und Timeouts wissen Sie nicht, ob eine Sendung durchgegangen ist. Mit einem Idempotenzschlüssel lässt sich die Sendung gefahrlos wiederholen: Hat Emailit bereits eine Anfrage mit demselben Schlüssel angenommen, gibt es die ursprüngliche Antwort zurück, statt die E-Mail erneut zu senden. Diese Seite ist die Referenz für den Header `Idempotency-Key`. Eine Schritt-für-Schritt-Anleitung finden Sie unter [Idempotente Anfragen](/de/docs/email-api/idempotency/).

## Unterstützte Endpunkte

| Endpunkt | |
| --- | --- |
| `POST /emails` | [E-Mail senden](/de/docs/api-reference/emails/send/) |
| `POST /emails/{id}/forward` | [E-Mail weiterleiten](/de/docs/api-reference/emails/forward/) |

Andere Endpunkte ignorieren den Header. Das Erstellen einer Domain, eines API-Schlüssels, einer Kontaktliste oder eines Kontakts lässt sich ohnehin gefahrlos wiederholen: Eine zweite Anfrage mit demselben Namen oder derselben E-Mail-Adresse gibt `409` und das vorhandene Objekt in `existing` zurück, statt ein Duplikat zu erstellen.

## Schlüssel senden

Fügen Sie einen Header `Idempotency-Key` hinzu, dessen Wert für die zu sendende E-Mail eindeutig ist, etwa eine UUID oder eine ID aus Ihrem eigenen System:

**cURL**

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "from": "Acme <orders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order #1042",
    "html": "<p>Thanks for your order.</p>"
  }'
```

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/emails', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `order-${order.id}-confirmation`,
  },
  body: JSON.stringify({
    from: 'Acme <orders@acme.com>',
    to: order.email,
    subject: `Your order #${order.id}`,
    html: '<p>Thanks for your order.</p>',
  }),
});
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.emailit.com/v2/emails",
    headers={
        "Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}",
        "Idempotency-Key": f"order-{order['id']}-confirmation",
    },
    json={
        "from": "Acme <orders@acme.com>",
        "to": order["email"],
        "subject": f"Your order #{order['id']}",
        "html": "<p>Thanks for your order.</p>",
    },
    timeout=30,
)
```

Erzeugen Sie den Schlüssel einmal pro E-Mail, vor dem ersten Versuch, und senden Sie bei jeder Wiederholung dieser E-Mail denselben Schlüssel.

## So funktionieren Schlüssel

| Regel | Details |
| --- | --- |
| Format | 1 bis 256 Zeichen. Nur Buchstaben, Ziffern, Bindestriche (`-`) und Unterstriche (`_`). |
| Geltungsbereich | Pro Workspace. Schlüssel aus verschiedenen Workspaces kollidieren nie, aber beide Endpunkte teilen sich einen Namensraum. Verwenden Sie den Schlüssel einer Sendung deshalb nicht für eine Weiterleitung. |
| Lebensdauer | Die Antwort auf eine erfolgreiche Anfrage wird nach deren Abschluss 24 Stunden lang gespeichert. |
| Wiederholte Anfragen | Eine Anfrage mit einem gespeicherten Schlüssel gibt die gespeicherte Antwort mit dem Status `200` zurück. Es wird keine E-Mail gesendet, es werden keine Credits verbraucht, und die Versandlimits werden nicht belastet. |
| Abgleich | Nur der Schlüssel wird verglichen, nicht der Anfrage-Body. Eine andere Anfrage mit einem bereits verwendeten Schlüssel gibt die erste Antwort zurück. |
| Fehlschläge | Schlägt eine Anfrage mit einem beliebigen Fehler fehl, wird nichts gespeichert und der Schlüssel wird freigegeben. Sie können die Anfrage also korrigieren und mit demselben Schlüssel wiederholen. |
| Nebenläufigkeit | Solange eine Anfrage mit einem Schlüssel noch läuft, gibt eine weitere Anfrage mit demselben Schlüssel `409` zurück. Die Sperre wird freigegeben, wenn die erste Anfrage abgeschlossen ist, und läuft nach höchstens 15 Minuten ab. |

Eine wiederholte Anfrage durchläuft trotzdem die Authentifizierung und die Prüfung der [Versandlimits](/de/docs/api-reference/rate-limits/) pro Sekunde und pro Tag. Sie kann also `401` oder `429` zurückgeben. Weiterleitungen zählen außerdem zum stündlichen Limit für Weiterleitungen, auch wenn die gespeicherte Antwort zurückgegeben wird.

## Fehler

**400**

```json
{
  "error": "Invalid Idempotency-Key"
}
```

**409**

```json
{
  "error": "Idempotency key in progress",
  "message": "A request with this Idempotency-Key is already being processed. Retry shortly with the same key."
}
```

**503**

```json
{
  "error": "Idempotency unavailable",
  "message": "Unable to process Idempotency-Key right now. Retry the request with the same key."
}
```

| Status | `error` | Ursache | Was zu tun ist |
| --- | --- | --- | --- |
| `400` | `Invalid Idempotency-Key` | Der Schlüssel ist leer, länger als 256 Zeichen oder enthält andere Zeichen als Buchstaben, Ziffern, `-` und `_`. | Verwenden Sie eine UUID oder einen anderen sicheren Wert. |
| `409` | `Idempotency key in progress` | Eine Anfrage mit demselben Schlüssel wird noch verarbeitet. | Warten Sie eine Sekunde und wiederholen Sie die Anfrage mit demselben Schlüssel. Sobald die erste Anfrage abgeschlossen ist, erhalten Sie die gespeicherte Antwort. |
| `503` | `Idempotency unavailable` | Emailit kann den Schlüssel gerade nicht prüfen. Die Anfrage wurde nicht verarbeitet. | Wiederholen Sie die Anfrage nach kurzer Wartezeit mit demselben Schlüssel. |

Emailit führt eine Anfrage nie ohne Idempotenzprüfung aus: Lässt sich der Schlüssel nicht prüfen, schlägt die Anfrage mit `503` fehl, statt ein Duplikat zu riskieren.

## Gute Schlüssel wählen

- Leiten Sie den Schlüssel von dem ab, worüber Sie benachrichtigen, etwa `order-1042-confirmation` oder `password-reset-<token-id>`. So verwendet auch eine Wiederholung durch einen anderen Worker oder nach einem Neustart denselben Schlüssel.
- Verwenden Sie nur dann eine neue UUID, wenn die E-Mail keine natürliche ID hat, und speichern Sie sie vor dem ersten Versuch zusammen mit dem Job.
- Verwenden Sie einen Schlüssel innerhalb von 24 Stunden nicht für eine andere E-Mail. Sie würden die Antwort der ersten E-Mail erhalten, und die zweite E-Mail würde nicht gesendet.

## Siehe auch

  - [Idempotente Anfragen](/de/docs/email-api/idempotency/): Eine Anleitung für sicher wiederholbares Senden.
  - [Rate Limits](/de/docs/api-reference/rate-limits/): Backoff und Wiederholung mit Beispielcode.

---
Quelle: https://emailit.com/de/docs/api-reference/idempotency/