Idempotenz

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.

Unterstützte Endpunkte

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 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>"
  }'

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>',
  }),
});

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

Eine wiederholte Anfrage durchläuft trotzdem die Authentifizierung und die Prüfung der Versandlimits 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

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

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

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

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