Chaves de idempotência

Redes falham. Se uma requisição expira, você não tem como saber se o e-mail foi aceito. Envie um cabeçalho Idempotency-Key e tente de novo à vontade: a mesma chave com o mesmo corpo retorna a resposta original e envia o e-mail uma única vez.

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

Regras

Compatível com POST /emails e POST /emails/batch.
A chave tem de 1 a 256 caracteres.
As chaves são restritas à sua equipe e lembradas por 24 horas.
Mesma chave e mesmo corpo: a resposta armazenada é retornada (mesmo status, mesmo corpo) e nada novo é enviado.
Mesma chave e um corpo diferente: 409 invalid_idempotent_request.
Mesma chave enquanto a primeira requisição ainda está em andamento: 409 concurrent_idempotent_requests. Aguarde um instante e tente de novo.
Uma chave fora do intervalo de 1 a 256 caracteres: 400 invalid_idempotency_key.
Requisições que falham não são armazenadas, então você pode corrigir o problema e reutilizar a chave.

“Mesmo corpo” significa que o JSON interpretado é idêntico. Alterar qualquer campo, inclusive scheduled_at: "in 1 hour" (que é avaliado no momento da requisição), conta como uma requisição diferente.

Como escolher as chaves

Derive a chave do evento de negócio, não de um valor aleatório gerado na hora da nova tentativa:

Bom	Ruim
`receipt-order-1042`	`crypto.randomUUID()` a cada tentativa
`welcome-user-u_1042`	`Date.now()`
`digest-2026-w43-chunk-3`	A mesma constante para todos os e-mails