Chiavi di idempotenza

Le reti falliscono. Se una richiesta va in timeout non puoi sapere se l’email è stata accettata. Invia un header Idempotency-Key e riprova liberamente: la stessa chiave con lo stesso corpo restituisce la risposta originale e invia l’email una sola volta.

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

Regole

Supportato su POST /emails e POST /emails/batch.
La chiave è lunga da 1 a 256 caratteri.
Le chiavi hanno come ambito il tuo team e vengono ricordate per 24 ore.
Stessa chiave e stesso corpo della richiesta: viene restituita la risposta salvata (stesso stato, stesso corpo) e non viene inviato nulla di nuovo.
Stessa chiave e un corpo diverso: 409 invalid_idempotent_request.
Stessa chiave mentre la prima richiesta è ancora in corso: 409 concurrent_idempotent_requests. Attendi un momento e riprova.
Una chiave fuori dall’intervallo da 1 a 256 caratteri: 400 invalid_idempotency_key.
Le richieste fallite non vengono salvate, quindi puoi risolvere il problema e riutilizzare la chiave.

“Stesso corpo” significa che il JSON analizzato è identico. Cambiare qualsiasi campo, incluso scheduled_at: "in 1 hour" (che viene valutato al momento della richiesta), conta come una richiesta diversa.

Scegliere le chiavi

Ricava la chiave dall’evento di business, non da un valore casuale generato al momento del nuovo tentativo:

Buone	Cattive
`receipt-order-1042`	`crypto.randomUUID()` a ogni tentativo
`welcome-user-u_1042`	`Date.now()`
`digest-2026-w43-chunk-3`	La stessa costante per ogni email