冪等性と再試行

HTTP リクエストでは Idempotency-Key を指定します。任意ですが、省略すると受付ごとに新しいメールになります。SDK はキーを指定しない限り、新しい準備済みリクエストごとにキーを生成します。

キーは英字・数字・_・.・:・- の 1〜128 文字です。welcome-123 などを使い、元の宛先、テンプレート、変数、言語とともに再利用します。

send() は 1 回だけ試行します。prepare(...).retry(3).send() は最大 3 回の追加試行を行います。回数を省略した retry() も 3 回で、0〜5 を指定できます。以下は JavaScript SDK の例です。

const email = sendery.prepare({
  to: '[email protected]',
  template: 'welcome',
  data: { name: 'Alex', action_url: 'https://example.com/start' },
}, 'welcome-123');

const receipt = await email.retry(3).send();

retry() を有効にすると、接続エラー、読み取れないレスポンス、500、502、503、504、429 rate_limited を再試行します。試行間に待機し、Retry-After に従います。待機時間が 30 秒を超える場合は例外を返すため、後から再試行してください。検証、支払い、送信枠、冪等性のエラーは再試行しません。

prepare() はメールのデータとキーを保持します。同じオブジェクトで再試行してください。アプリを再起動した場合やリクエストを作り直す場合は、保存済みのキーと元の内容を渡します。同じキーで内容を変えると 409 を返します。

一致する再試行は 200 と元のメッセージ ID、現在の状態を返します。失敗した配信を再送する操作ではありません。意図的に再送する場合は新しいキーを使います。キーはプロジェクト単位で、メッセージ記録が存在する間有効です。