# Idempotence

> Bezpečně opakujte odeslání e-mailů s hlavičkou Idempotency-Key. Které endpointy ji podporují, formát a platnost klíče, 24hodinové okno pro opakované odpovědi a chyby.

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](/cs/docs/email-api/idempotency/).

## Podporované endpointy

| Endpoint | |
| --- | --- |
| `POST /emails` | [Odeslání e-mailu](/cs/docs/api-reference/emails/send/) |
| `POST /emails/{id}/forward` | [Přeposlání e-mailu](/cs/docs/api-reference/emails/forward/) |

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**

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

**Node.js**

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

**Python**

```python
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í

| Pravidlo | Podrobnosti |
| --- | --- |
| Formát | 1 až 256 znaků. Jen písmena, číslice, pomlčky (`-`) a podtržítka (`_`). |
| Platnost | Pro každý workspace zvlášť. Klíče z různých workspace se nikdy nestřetnou, ale oba endpointy sdílejí jeden jmenný prostor, takže klíč z odeslání nepoužívejte znovu pro přeposlání. |
| Doba uložení | Odpověď na úspěšný požadavek se uchovává 24 hodin od jeho dokončení. |
| Opakované odpovědi | Požadavek s uloženým klíčem vrátí uloženou odpověď se stavem `200`. Neodešle se žádný e-mail, nespotřebují se žádné kredity a nezapočítá se do limitů odesílání. |
| Porovnání | Porovnává se jen klíč, ne tělo požadavku. Jiný požadavek s už použitým klíčem vrátí první odpověď. |
| Selhání | Pokud požadavek selže s jakoukoli chybou, nic se neuloží a klíč se uvolní, takže můžete požadavek opravit a zopakovat se stejným klíčem. |
| Souběh | Dokud požadavek s daným klíčem ještě běží, jiný požadavek se stejným klíčem vrátí `409`. Zámek se uvolní, jakmile první požadavek skončí, a vyprší nejpozději po 15 minutách. |

I opakovaný požadavek prochází autentizací a kontrolou [limitů odesílání](/cs/docs/api-reference/rate-limits/) 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

**400**

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

**409**

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

**503**

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

| Stav | `error` | Příčina | Co dělat |
| --- | --- | --- | --- |
| `400` | `Invalid Idempotency-Key` | Klíč je prázdný, delší než 256 znaků, nebo obsahuje jiné znaky než písmena, číslice, `-` a `_`. | Použijte UUID nebo jinou bezpečnou hodnotu. |
| `409` | `Idempotency key in progress` | Požadavek se stejným klíčem se ještě zpracovává. | Vteřinu počkejte a požadavek zopakujte se stejným klíčem. Jakmile první požadavek skončí, dostanete uloženou odpověď. |
| `503` | `Idempotency unavailable` | Emailit teď nemůže klíč zkontrolovat. Požadavek se nezpracoval. | Po krátké prodlevě požadavek zopakujte se stejným klíčem. |

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í

  - [Idempotentní požadavky](/cs/docs/email-api/idempotency/): Návod na odesílání, které lze bezpečně opakovat.
  - [Limity rychlosti](/cs/docs/api-reference/rate-limits/): Rostoucí odstup a opakování s ukázkovým kódem.

---
Zdroj: https://emailit.com/cs/docs/api-reference/idempotency/