멱등성 키

네트워크는 실패할 수 있습니다. 요청이 시간 초과되면 이메일이 접수되었는지 알 수 없습니다. Idempotency-Key 헤더를 보내면 마음 놓고 재시도할 수 있습니다. 같은 본문에 같은 키를 사용하면 원래 응답이 반환되고 이메일은 한 번만 발송됩니다.

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

규칙

POST /emails와 POST /emails/batch에서 지원됩니다.
키는 1자 이상 256자 이하입니다.
키는 팀 단위로 적용되며 24시간 동안 기억됩니다.
같은 키와 같은 요청 본문: 저장된 응답이 반환되고(상태와 본문 동일) 새로 발송되는 것은 없습니다.
같은 키와 다른 본문: 409 invalid_idempotent_request.
첫 번째 요청이 아직 처리 중일 때 같은 키: 409 concurrent_idempotent_requests. 잠시 기다렸다가 다시 시도하세요.
1자 이상 256자 이하를 벗어난 키: 400 invalid_idempotency_key.
실패한 요청은 저장되지 않으므로 문제를 고친 뒤 같은 키를 다시 사용할 수 있습니다.

“같은 본문”이란 파싱한 JSON이 동일하다는 뜻입니다. scheduled_at: "in 1 hour"(요청 시점에 계산됨)를 포함해 어떤 필드든 바뀌면 다른 요청으로 취급됩니다.

키 선택

재시도할 때마다 새로 만든 무작위 값이 아니라 비즈니스 이벤트에서 키를 만드세요.

좋은 예	나쁜 예
`receipt-order-1042`	시도할 때마다 `crypto.randomUUID()`
`welcome-user-u_1042`	`Date.now()`
`digest-2026-w43-chunk-3`	모든 이메일에 같은 상수