# Idempotenza

> Ritenta in sicurezza gli invii di email con l’header Idempotency-Key. Quali endpoint lo supportano, formato e ambito della chiave, la finestra di ripetizione di 24 ore e i relativi errori.

Con gli errori di rete e i timeout non sai con certezza se un invio è andato a buon fine. Una chiave di idempotenza ti permette di ritentare l’invio in sicurezza: se Emailit ha già accettato una richiesta con la stessa chiave, restituisce la risposta originale invece di inviare di nuovo l’email. Questa pagina è il riferimento per l’header `Idempotency-Key`. Per una guida passo passo, vedi [Richieste idempotenti](/it/docs/email-api/idempotency/).

## Endpoint supportati

| Endpoint | |
| --- | --- |
| `POST /emails` | [Invia un’email](/it/docs/api-reference/emails/send/) |
| `POST /emails/{id}/forward` | [Inoltra un’email](/it/docs/api-reference/emails/forward/) |

Gli altri endpoint ignorano l’header. La creazione di un dominio, di una chiave API, di una lista o di un contatto si può già ritentare in sicurezza: una seconda richiesta con lo stesso nome o la stessa email restituisce `409` e l’oggetto `existing` invece di creare un duplicato.

## Invia una chiave

Aggiungi un header `Idempotency-Key` con un valore univoco per l’email che stai inviando, ad esempio un UUID o un ID del tuo sistema:

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

Genera la chiave una sola volta per ogni email, prima del primo tentativo, e invia la stessa chiave a ogni nuovo tentativo per quell’email.

## Come funzionano le chiavi

| Regola | Dettagli |
| --- | --- |
| Formato | Da 1 a 256 caratteri. Solo lettere, cifre, trattini (`-`) e trattini bassi (`_`). |
| Ambito | Per workspace. Le chiavi di workspace diversi non entrano mai in conflitto, ma i due endpoint condividono un unico spazio dei nomi, quindi non riusare per un inoltro la chiave di un invio. |
| Durata | La risposta a una richiesta riuscita viene conservata per 24 ore dal suo completamento. |
| Ripetizioni | Una richiesta con una chiave memorizzata restituisce la risposta memorizzata con stato `200`. Non viene inviata alcuna email, non vengono consumati crediti e la richiesta non viene conteggiata nei limiti di invio. |
| Corrispondenza | Viene confrontata solo la chiave, non il corpo della richiesta. Una richiesta diversa con una chiave già usata restituisce la prima risposta. |
| Errori | Se una richiesta non riesce, con qualsiasi errore, non viene memorizzato nulla e la chiave viene liberata, così puoi correggere la richiesta e ritentare con la stessa chiave. |
| Concorrenza | Finché una richiesta con una chiave è ancora in esecuzione, un’altra richiesta con la stessa chiave restituisce `409`. Il blocco viene rilasciato quando la prima richiesta termina e scade al massimo dopo 15 minuti. |

Una richiesta ripetuta passa comunque per l’autenticazione e per il controllo dei [limiti di invio](/it/docs/api-reference/rate-limits/) al secondo e giornalieri, quindi può restituire `401` o `429`. Gli inoltri rientrano inoltre nel limite orario degli inoltri, anche quando la risposta viene ripetuta.

## Errori

**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."
}
```

| Stato | `error` | Causa | Cosa fare |
| --- | --- | --- | --- |
| `400` | `Invalid Idempotency-Key` | La chiave è vuota, supera i 256 caratteri o contiene caratteri diversi da lettere, cifre, `-` e `_`. | Usa un UUID o un altro valore sicuro. |
| `409` | `Idempotency key in progress` | Una richiesta con la stessa chiave è ancora in elaborazione. | Attendi un secondo e ritenta con la stessa chiave. Quando la prima richiesta sarà terminata, riceverai la risposta memorizzata. |
| `503` | `Idempotency unavailable` | Al momento Emailit non riesce a controllare la chiave. La richiesta non è stata elaborata. | Ritenta con la stessa chiave dopo una breve attesa. |

Emailit non invia mai una richiesta senza il controllo di idempotenza: se la chiave non può essere controllata, la richiesta non riesce con `503` invece di rischiare un duplicato.

## Scegli chiavi adatte

- Ricava la chiave da ciò che stai notificando, come `order-1042-confirmation` o `password-reset-<token-id>`, così un nuovo tentativo da un altro worker o dopo un riavvio usa la stessa chiave.
- Usa un nuovo UUID solo quando l’email non ha un ID naturale, e salvalo insieme al job prima del primo tentativo.
- Non riusare una chiave per un’email diversa entro 24 ore. Riceveresti la risposta della prima email e la seconda non verrebbe inviata.

## Vedi anche

  - [Richieste idempotenti](/it/docs/email-api/idempotency/): Una guida agli invii da ritentare in sicurezza.
  - [Limiti di frequenza](/it/docs/api-reference/rate-limits/): Backoff e nuovi tentativi, con codice di esempio.

---
Fonte: https://emailit.com/it/docs/api-reference/idempotency/