Idempotence

Po chybě sítě nebo vypršení časového limitu nevíte jistě, jestli odeslání prošlo. Idempotenční klíč (idempotency key) umožňuje odeslání bezpečně zopakovat: pokud Emailit požadavek se stejným klíčem už přijal, vrátí původní odpověď a e-mail znovu neodešle. Tato stránka je referencí k hlavičce Idempotency-Key. Podrobný návod najdete na stránce Idempotentní požadavky.

Podporované endpointy

Ostatní endpointy hlavičku ignorují. Vytvoření domény, API klíče, seznamu kontaktů nebo kontaktu lze bezpečně opakovat už teď: druhý požadavek se stejným názvem nebo e-mailem vrátí 409 a objekt existing, místo aby vytvořil duplicitu.

Pošlete klíč

Přidejte hlavičku Idempotency-Key s hodnotou, která je jedinečná pro odesílaný e-mail, například UUID nebo ID z vašeho vlastního systému:

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,
)

Klíč vygenerujte pro každý e-mail jednou, ještě před prvním pokusem, a stejný klíč posílejte při každém opakování tohoto e-mailu.

Jak klíče fungují

I opakovaný požadavek prochází autentizací a kontrolou limitů odesílání za sekundu a za den, takže může vrátit 401, nebo 429. Přeposlání se navíc počítá do hodinového limitu přeposílání, i když se vrátí uložená odpověď.

Chyby

{
  "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 nikdy nezpracuje požadavek bez kontroly idempotence: pokud klíč nelze zkontrolovat, požadavek selže s 503, aby nevznikl duplicitní e-mail.

Volte dobré klíče

• Odvoďte klíč od toho, o čem informujete, například order-1042-confirmation nebo password-reset-<token-id>, aby opakování z jiného procesu nebo po restartu použilo stejný klíč.
• Náhodné UUID použijte, jen pokud e-mail nemá přirozené ID, a uložte ho k úloze ještě před prvním pokusem.
• Během 24 hodin nepoužívejte stejný klíč pro jiný e-mail. Dostali byste odpověď na první e-mail a druhý by se neodeslal.

Související