技術解説 · 出典付きの回答

冪等キーとは？メールの重複送信を防ぐ仕組み

冪等キーは、操作が確実に一度だけ実行されるように、クライアントが生成してAPIリクエストで送る一意の値です。同じキーでリクエストが再試行されると、サーバーは重複を認識し、処理を再度実行せずに元のレスポンスを返します。

仕組み

クライアントが冪等キー付きのリクエストを送ると、サーバーはキーとその結果のレスポンスをキャッシュに保存します。同じキーを持つ後続のリクエストが届くと、サーバーは実行ロジックをスキップし、キャッシュされたレスポンスをそのまま返します。この仕組みは、ネットワークのタイムアウトによってリクエストがサーバーに届いたかどうかクライアントが判断できなくなる分散システムにとって重要です。

送信者にとっての重要性

トランザクションメールでは、同じメッセージを2回送るとユーザー体験が損なわれ、迷惑メール報告も増えかねません。冪等キーを使えば、受信者に重複メールを送るリスクを負うことなく、失敗したネットワーク呼び出しに対して積極的な再試行ロジックを実装できます。これにより、配信パイプライン全体で信頼性と一貫性を確保できます。

運用上の考慮事項

衝突を避けるため、キーはUUIDやエントロピーの高いランダムな文字列で生成してください。サーバーは通常、24時間後にこれらのキーを失効させます。キーはメッセージの具体的な意図に結び付けておく必要があります。同じキーのままメール本文や受信者を変更した場合は、キャッシュされた成功レスポンスではなくエラーになるべきです。

実装例

あるSaaSアプリケーションが、パスワードリセットメール用に一意のキーを生成したとします。アプリはメールAPIを呼び出しますが、レスポンスを受け取る前に接続が切れてしまいます。アプリは同じキーを使ってリクエストを再試行します。APIはそのキーがすでに存在することを確認し、ユーザーに2通目のメールを送らずに200 OKを返します。SendHQの無料ツールは、開発者がメールインフラを効率よく管理するのに役立ちます。

エラー処理

リクエストの内容が変更されているのに既存の冪等キーで送られた場合、サーバーは競合エラーを返すべきです。これにより、異なるメッセージでキーを誤って再利用することを防げます。適切な処理としては、こうした競合を捕捉し、更新したリクエストペイロード用に新しいキーを生成します。

よく寄せられる質問

冪等キーはメッセージIDと同じものですか？

いいえ。メッセージIDは処理後にサーバーが割り当てるもので、冪等キーはリクエストを送る前にクライアントが割り当てるものです。

冪等キーが失効するとどうなりますか？

キーがサーバーのキャッシュから失効すると、再試行は新しいリクエストとして扱われるため、メールが重複して送信されることがあります。

冪等キーに最適なデータ型は何ですか？

UUID v4が業界標準です。分散システム全体でも衝突の確率がごくわずかに抑えられるためです。

一次情報源

さらに学ぶ

メールAPIトランザクションメールAPIAPIでメールを送信SaaS向けメールAPI