Idempotence

Après une erreur réseau ou un timeout, vous ne savez pas si un envoi a abouti. Une clé d’idempotence permet de relancer l’envoi sans risque : si Emailit a déjà accepté une requête avec la même clé, il renvoie la réponse d’origine au lieu d’envoyer à nouveau l’e-mail. Cette page est la référence de l’en-tête Idempotency-Key. Pour un guide pas à pas, consultez Envois idempotents.

Endpoints pris en charge

Les autres endpoints ignorent l’en-tête. La création d’un domaine, d’une clé API, d’une liste de contacts ou d’un contact peut déjà être relancée sans risque : une deuxième requête avec le même nom ou la même adresse e-mail renvoie 409 et l’objet existing au lieu de créer un doublon.

Envoyer une clé

Ajoutez un en-tête Idempotency-Key dont la valeur est propre à l’e-mail que vous envoyez, comme un UUID ou un ID issu de votre propre système :

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

Générez la clé une seule fois par e-mail, avant la première tentative, et envoyez la même clé à chaque relance de cet e-mail.

Fonctionnement des clés

Une requête rejouée passe quand même par l’authentification et par la vérification des limites d’envoi par seconde et quotidienne : elle peut donc renvoyer 401 ou 429. Les transferts sont aussi décomptés de la limite horaire de transferts, même lorsque la réponse est rejouée.

Erreurs

{
  "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 ne traite jamais une requête sans vérifier son idempotence : si la clé ne peut pas être vérifiée, la requête échoue avec 503 plutôt que de risquer un doublon.

Choisir de bonnes clés

• Dérivez la clé de l’objet de la notification, comme order-1042-confirmation ou password-reset-<token-id>, pour qu’une relance depuis un autre worker ou après un redémarrage utilise la même clé.
• N’utilisez un nouvel UUID que si l’e-mail n’a pas d’identifiant naturel, et enregistrez-le avec la tâche avant la première tentative.
• Ne réutilisez pas une clé pour un autre e-mail dans les 24 heures. Vous obtiendriez la réponse du premier e-mail et le second ne serait pas envoyé.

Voir aussi