Idempotence (Idempotency-Key)
Idempotence znamená, že opakování stejného požadavku má stejný výsledek jako jeho jediné provedení; u e-mailového API ji zajišťuje hlavička Idempotency-Key, díky které se při opakovaném odeslání téhož požadavku e-mail nepošle dvakrát.
Při výpadku sítě aplikace neví, jestli požadavek na odeslání dorazil; bez idempotence buď riskuje dvojí potvrzení objednávky, nebo žádné. S klíčem (např. order-10234-confirmation) server při druhém požadavku se stejným klíčem vrátí původní odpověď a nic nového neodešle. Klíč se obvykle pamatuje 24 hodin.
Idempotence je důležitá i při příjmu webhooků: stejná událost může dorazit víckrát (opakování po timeoutu), proto si aplikace ukládá ID události a duplicitu ignoruje. U SMTP idempotence chybí, opakování po chybě spojení může zprávu zdvojit; proto se pro kritické e-maily hodí API.
POST /api/email/send
Authorization: Bearer <clientId>:<secret>
Idempotency-Key: order-10234-confirmation
Content-Type: application/jsonREST API TopEmail hlavičku Idempotency-Key podporuje; webhook email.status nese ID události, podle kterého duplicitu snadno odfiltrujete.