Clés d'idempotence

Les réseaux tombent en panne. Si une requête expire, vous ne pouvez pas savoir si l’e-mail a été accepté. Envoyez un en-tête Idempotency-Key et réessayez sans crainte : la même clé avec le même corps renvoie la réponse d’origine et n’envoie l’e-mail qu’une seule fois.

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send(
  { from: "Acme <hello@acme.com>", to: "user@example.com", subject: "Receipt", html: "<p>Thanks</p>" },
  { idempotencyKey: "receipt-order-1042" },
);

console.log(error ?? data);

curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" \
  -H "Idempotency-Key: receipt-order-1042" \
  -H "Content-Type: application/json" \
  -d '{ "from": "Acme <hello@acme.com>", "to": ["user@example.com"], "subject": "Receipt", "html": "<p>Thanks</p>" }'

requests.post(
    "https://api.spacepost.dev/emails",
    headers={
        "Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}",
        "Idempotency-Key": "receipt-order-1042",
    },
    json={"from": "Acme <hello@acme.com>", "to": ["user@example.com"], "subject": "Receipt", "html": "<p>Thanks</p>"},
)

Règles

Pris en charge sur POST /emails et POST /emails/batch.
La clé fait de 1 à 256 caractères.
Les clés sont propres à votre équipe et mémorisées pendant 24 heures.
Même clé et même corps de requête : la réponse stockée est renvoyée (même statut, même corps), rien de nouveau n’est envoyé.
Même clé et corps différent : 409 invalid_idempotent_request.
Même clé alors que la première requête est encore en cours : 409 concurrent_idempotent_requests. Patientez un instant et réessayez.
Une clé de moins de 1 ou de plus de 256 caractères : 400 invalid_idempotency_key.
Les requêtes qui échouent ne sont pas stockées : vous pouvez donc corriger le problème et réutiliser la clé.

« Même corps » signifie que le JSON analysé est identique. Modifier un champ, y compris scheduled_at: "in 1 hour" (évalué au moment de la requête), compte comme une requête différente.

Choisir les clés

Dérivez la clé de l’événement métier, et non d’une valeur aléatoire générée au moment de la nouvelle tentative :

Bon	Mauvais
`receipt-order-1042`	`crypto.randomUUID()` à chaque tentative
`welcome-user-u_1042`	`Date.now()`
`digest-2026-w43-chunk-3`	La même constante pour tous les e-mails