Zuletzt aktualisiert: 2026-03-03•3 Min. Lesezeit

Idempotenz

Idempotenz verhindert doppelte Versendungen, wenn Ihr System eine Anfrage wiederholt.

Funktionsweise

Fügen Sie bei jeder Sendeanfrage einen Idempotency-Key-Header hinzu. Der Key ist eine eindeutige Zeichenfolge, die Sie generieren — typischerweise eine UUID, die mit dem Geschäftsereignis verknüpft ist.

curl -X POST https://truncus.co/api/v1/emails/send \
  -H "Authorization: Bearer $TRUNCUS_API_KEY" \
  -H "Idempotency-Key: bestellung_12345_rechnung" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "abrechnung@ihredomain.de",
    "subject": "Rechnung #1234",
    "html": "<p>Ihre Rechnung ist bereit.</p>"
  }'

Verhalten

Wenn eine Anfrage mit demselben Idempotency-Key bereits verarbeitet wurde:

  • Die ursprüngliche message_id und der status werden zurückgegeben
  • Es wird keine neue E-Mail gesendet
  • Die Response ist identisch mit der ursprünglichen

Idempotency-Keys verfallen nach 24 Stunden. Nach Ablauf löst derselbe Key einen neuen Versand aus.

Wann Idempotenz verwenden

  • Zahlungsbestätigungen — eine E-Mail pro Zahlung, unabhängig von Wiederholungen
  • Webhook-Handler — sicher wiederholbar bei Zustellungsfehler
  • Agent-Workflows — erneute Ausführungen liefern dasselbe Ergebnis
  • Jeder Versand, bei dem Duplikate den Empfänger beeinflussen würden

SDK-Verwendung

const response = await truncus.emails.send({
  to: 'user@example.com',
  from: 'abrechnung@ihredomain.de',
  subject: 'Rechnung #1234',
  html: rechnungsHtml,
}, {
  idempotencyKey: `bestellung_${bestellId}_rechnung`
})

Key-Design

Ein guter Idempotency-Key kodiert das Geschäftsereignis, nicht die Anfrage:

// Gut: am Ereignis orientiert
const key = `zahlung_${zahlungId}_quittung`

// Gut: stabil bei Wiederholungen
const key = `nutzer_${nutzerId}_willkommen`

// Schlecht: ändert sich bei Wiederholung
const key = crypto.randomUUID()

Wenn kein Idempotency-Key angegeben wird, wird jede Anfrage als neuer Versand behandelt.

Idempotenz