冪等キー

ネットワークは失敗することがあります。リクエストがタイムアウトした場合、メールが受理されたかどうかは分かりません。Idempotency-Key ヘッダーを付けて送信すれば、自由に再試行できます。同じキーと同じボディなら元のレスポンスが返り、メールが送信されるのは1 回だけです。

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`	すべてのメールで同じ定数