Přejít na obsah
Dokumentace

Návod

Hlavičkou Idempotency-Key bezpečně opakujte požadavky na odeslání a přeposlání. Formát klíče, 24hodinové okno, opakované odpovědi, odpovědi 409 a 503 a volba klíčů.

Aktualizováno 1. 10. 2026

Sítě selhávají. Když u požadavku na odeslání vyprší časový limit, nevíte, jestli ho Emailit přijal, a když ho odešlete znovu, může váš zákazník dostat e-mail dvakrát. Hlavička Idempotency-Key dělá opakování bezpečným: Emailit zpracuje první požadavek a na každé opakování se stejným klíčem vrátí stejnou odpověď.

Jak to funguje

Přidejte hlavičku Idempotency-Key k POST /emails nebo POST /emails/{id}/forward.

  1. První požadavek. Emailit klíč pro váš workspace zarezervuje a požadavek zpracuje.
  2. Úspěch. Emailit uloží odpověď na 24 hodin. Každý požadavek se stejným klíčem v tomto okně dostane uloženou odpověď s 200 a žádný nový e-mail se nevytvoří.
  3. Selhání. Pokud požadavek selže, například s 400 nebo 402, Emailit klíč uvolní. Opravte problém a požadavek zopakujte se stejným klíčem.
  4. Překryv. Pokud dorazí druhý požadavek, zatímco první ještě probíhá, dostane 409 a nic se neodešle. Za chvíli ho zopakujte se stejným klíčem.

Klíče platí v rámci vašeho workspace, takže dva workspace mohou použít stejný klíč bez konfliktu.

Formát klíče

Pravidlo Hodnota
Délka 1 až 256 znaků
Znaky Písmena A–Z a a–z, číslice 0–9, spojovník - a podtržítko _
Platnost Pro každý workspace zvlášť
Okno 24 hodin od první úspěšné odpovědi

Klíč s jinými znaky, například : nebo /, se odmítne s 400 Invalid Idempotency-Key.

Zvolte klíč

Odvoďte klíč od události, která e-mail způsobuje, aby každá cesta opakování vytvořila stejný klíč:

E-mail Příklad klíče
Potvrzení objednávky order-1042-receipt
Obnovení hesla password-reset-7f3c9a1e (ID tokenu pro obnovení)
Týdenní přehled digest-user-881-2026-w40
Úloha na pozadí ID úlohy, nebo UUID, které vygenerujete při zařazení úlohy do fronty a uložíte s ní

Vyhněte se klíčům, které se mezi pokusy mění, například časovým razítkům nebo UUID generovanému uvnitř smyčky opakování. Kvůli nim vypadá každé opakování jako nový požadavek.

Odešlete e-mail s idempotenčním klíčem

Příklady pro Node.js, Python a PHP opakují požadavek při chybách sítě a při odpovědích 409, 429 a 5xx a pokaždé použijí stejný klíč. Příklad pro cURL využívá vestavěné opakování curl, které pokrývá vypršení časového limitu, 429 a většinu odpovědí 5xx.

Terminal
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  --retry 3 \
  -d '{
    "from": "Acme <orders@acme.com>",
    "to": "ada@example.com",
    "subject": "Receipt for order 1042",
    "text": "Thanks for your order."
  }'

Odpovědi

Stav Kdy Co dělat
200 První úspěšný požadavek nebo jeho opakování do 24 hodin Použijte odpověď. Opakovaná odpověď má stejné tělo včetně stejného id.
400 Invalid Idempotency-Key Klíč je prázdný, příliš dlouhý, nebo obsahuje neplatné znaky Opravte klíč.
409 Idempotency key in progress Požadavek se stejným klíčem se ještě zpracovává Chvíli počkejte a pak požadavek zopakujte se stejným klíčem.
503 Idempotency unavailable Emailit se nemohl spojit se svým úložištěm idempotenčních klíčů, a tak požadavek raději odmítl, než aby riskoval duplicitu Zopakujte požadavek se stejným klíčem.
Jakákoli jiná chyba Požadavek selhal a klíč se uvolnil Odstraňte příčinu a zopakujte požadavek se stejným klíčem.

Limity rychlosti se kontrolují před klíčem, takže i opakování může dostat 429. Počkejte podle hlavičky retry-after a odešlete stejný klíč znovu.

Byla tato stránka užitečná?

Děkujeme za zpětnou vazbu.

Děkujeme, čteme každou zprávu.