Idempotenza

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.

Endpoint supportati

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

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

Una richiesta ripetuta passa comunque per l’autenticazione e per il controllo dei limiti di invio 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

{
  "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 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