プロダクトチームはMailgun APIをどのように安全に実装すべきか

Mailgunを呼び出す前にプロダクトの操作を限定して定義する

アカウントの確認、領収書、セキュリティ通知、受信者が求めた通知など、承認済みのプロダクトイベントから始めます。プロバイダーの認証情報や任意のメッセージフォームをブラウザやモバイルクライアントに公開するのではなく、Mailgunは信頼できるアプリケーションサービスまたはキューワーカーの背後に置いてください。プロバイダー用のフィールドを作成する前に、呼び出し元、テナント、送信者ID、受信者、メッセージの種類、テンプレートを認可します。安定したイベントキー、テナント、テンプレートのリビジョン、承認済みのアドレス、初期状態を含む社内の送信記録を保存します。この記録が判断の基準となるシステムであり、Mailgunは転送のための依存先です。ビジネス上の意図とプロバイダーのペイロードを分けることで、再試行と監査がより安全になり、将来のプロバイダーの移行も可能な状態を保てます。受信者の配信設定、サプレッションのルール、レピュテーションのインシデントが、テンプレート上の非公式な慣習にならないよう、トランザクションのトラフィックと同意に依存するトラフィックはデータモデル上で区別しておくべきです。

正確な送信ドメインとDNSレコードを検証する

組織が管理するドメインを追加し、実際に選択した検証、送信ドメイン認証、トラッキング、受信の機能について、Mailgunが現在提示しているDNSレコードを公開します。DNSを変更する前に、既存のSPFとDMARCのレコードを確認してください。1つのホスト名に2つ目のSPFレコードを作成したり、担当者の了解なしに組織のDMARCポリシーを置き換えたりしないでください。隣接する親ドメインだけでなく、ワークロードが実際に使うFromと署名のIDを検証します。所有権、トラフィックの分離、移行の観点から必要であれば、用途別のサブドメインを使います。Mailgunが検証完了を報告したら、管理されたテストで受信したメッセージについて、表示されるFromアドレス、DKIMの署名ドメイン、Return-Path、認証結果、返信の挙動を確認します。プロバイダーの検証は、そのプロバイダーの設定チェックにパスしたことの証拠です。受信者の同意、宛先による受け付け、送信者レピュテーション、受信トレイへの到達を証明するものではありません。DNSの変更履歴とロールバックの手順は、プロバイダーのダッシュボードの外に保管してください。

スコープ付きの認証情報と正しいリージョンのエンドポイントを使う

Mailgunは、APIにHTTP Basic認証を使うことを文書化しており、API認証情報は権限と目的によって異なります。送信用のワーカーには、承認されたドメインと操作に必要な認証情報だけを渡すべきです。アカウントのプライマリキー、ドメインの送信用キー、Webhookの署名用の情報、下位の環境の認証情報は分けて管理します。秘密情報はマネージドなシークレットストアに直接保管し、それを必要とするサーバープロセスにだけ公開します。認証情報をクライアントのコード、ソース管理、URL、ログ、分析ツール、テンプレート、チケット、プロンプトに含めないでください。すべてのドメインが同じホストを使うと決めつけず、アカウントのリージョンに対応する文書化されたAPIのベースURLを選んでください。同等のスコープを持つ代わりの認証情報を作成し、ワーカーを更新し、管理されたトラフィックとイベントを確認してから古い認証情報を失効させる、という手順でローテーションを予行演習しておきます。予期しない認証や認可の失敗は、失効、誤ったリージョン、スコープのずれ、漏えいを示している可能性があるため、アラートを出してください。

耐久性のあるMessages APIリクエストを1つ組み立てる

Mailgunのドメイン単位のMessagesエンドポイントは、送信者、受信者、件名、テキストまたはHTMLの本文に加え、テンプレート、添付ファイル、ヘッダー、タグ、受信者ごとの変数、トラッキング、配信予約など、文書化されたオプションのマルチパートのフォームフィールドを受け付けます。公開するのは、プロダクトに必要なサブセットだけにしてください。アドレスの構文とテナントの所有を検証し、受信者と添付ファイルの数を制限し、改行インジェクションを拒否し、承認済みのテンプレートを型付きの変数でレンダリングします。プロバイダーのイベントやアクティビティ画面では、メッセージの内容とは別にメタデータが表示されることがあるため、タグ、カスタム変数、ヘッダーに秘密情報や不要な個人データを入れないでください。取得した社内のジョブから送信し、Mailgunが返したメッセージ識別子を、該当する試行とともに保存します。プロバイダー固有のオプション名は1つのアダプター内にとどめます。ビジネスロジックのコードには、Mailgunのすべてのフィールドやエラーの形を覚えさせるのではなく、受け付け済み、拒否、不確定という限定された結果を渡すべきです。

受け付けとあいまいさを軸に再試行を設計する

再試行する前にレスポンスを分類します。不正なフィールド、許可されていないドメイン、無効な認証情報、権限の失敗、恒久的なポリシーのエラーは、再実行するのではなく修正してください。対象となる転送の失敗、プロバイダーのサーバーエラー、レート制限されたリクエストは、指数バックオフ、ジッター、有限の試行回数、キューの滞留時間の上限を設けて再試行します。MailgunのAPIの受け付けのレスポンスは、プロバイダーが送信リクエストを処理のために受け付けたことを意味するもので、宛先サーバーがメッセージを受け付けたことの証明にはなりません。クライアントのタイムアウトはあいまいです。ワーカーがレスポンスを受け取れなかっただけで、Mailgunはリクエストを受け付けている可能性があります。そのジョブは不明の状態で保留し、保存しておいた相関データや後から届くイベントを検索し、意図したルールに従って突き合わせてから再送してください。Mailgunで転送するからといって、安定したアプリケーションのイベントキー、単一のワーカーによる取得、試行履歴、重複のリスクへの対策が不要になるわけではありません。認証情報、ドメイン、テンプレート、テナント、宛先のプロバイダーごとに、繰り返し発生する失敗についてアラートを出します。

解析する前にWebhookのリクエストを認証する

HTTPSのWebhookエンドポイントを設定し、Mailgunの署名の手順で使われるフィールドをそのまま保持します。Mailgunは、タイムスタンプ、トークン、そしてWebhookの署名キーから導出される署名を文書化しています。イベントを受け入れる前に、定数時間の比較で署名を検証し、アプリケーションの鮮度の許容範囲外のタイムスタンプを拒否します。リプレイへの耐性のために、必要に応じてトークンやイベント識別子を記録します。Webhookの署名キーは送信用の認証情報とは分けて管理し、テスト済みの手順でローテーションします。リクエストのサイズに上限を設け、本文を解析できたというだけで、URL、受信者、タグ、イベントのフィールドを信用しないでください。認証したら、成功を返す前にイベントを永続的に保存するかキューに入れます。こうすることで、プロセスがクラッシュしても配信の証拠が失われるのを防げます。Webhookの検証が証明するのは、設定した秘密情報のもとでの送信元と完全性です。アプリケーションがドメインとプロバイダーのメッセージ識別子を突き合わせるまでは、そのビジネスイベントが想定したテナントに属していることは証明されません。

Webhookの再送と重複したイベントを冪等に処理する

Mailgunは、エンドポイントが期待される成功のレスポンスを返さない場合のWebhookの再送の挙動を文書化しています。受信側は、遅延や重複した配信を前提にしなければなりません。安定したプロバイダーのイベント識別子があればそれを使って重複を排除し、なければ、異なる受信者やイベントの種類をまとめてしまうことのない、保守的な複合キーを使います。元の発生時刻と処理時刻は別々に保持します。再送が順不同で届いたというだけで、古い受け付け済みや配信済みの観測結果が、後から発生した恒久的な失敗、苦情、配信停止を消してしまわないよう、状態遷移は単調にしてください。成功を返すのは永続的に記録したあとだけにしますが、エンドポイントの信頼性を保つため、重いビジネス処理は非同期にします。署名の失敗、レスポンスのレイテンシー、再送の量、イベントの遅延、デッドレターの記録を監視します。プロバイダーの生のペイロードは、運用上およびポリシー上の必要性がある期間に限り、アクセスを制限しアドレスを最小限にして保持します。Webhookは証拠のフィードであり、テナントをまたいで受信者の履歴を公開してよいという許可ではありません。

配信を過大に評価せずにMailgunのイベントをモデル化する

Mailgunは、受け付け、配信、一時的な失敗と恒久的な失敗、開封、クリック、配信停止、苦情、保存、および関連する処理結果についてイベントの種類を文書化しています。これらの名前を社内のモデルに対応づけつつ、プロバイダーのイベントの種類、メッセージ識別子、受信者の範囲、タイムスタンプ、重大度、利用可能なSMTP応答を保持してください。acceptedは、Mailgunによる受け付けやキューの進行状況を表します。deliveredは文書化された配信の観測結果、一般には宛先サーバーによる受け付けを表しますが、最終的なメールボックスのフォルダはわかりません。開封とクリックはエンゲージメントの計測であって転送の証明ではなく、プライバシー保護の技術によって影響を受けることがあります。一時的な失敗であれば、転送システム内で上限を設けた再試行を行う理由になりますが、恒久的な失敗、苦情、配信停止は、後のアプリケーションのジョブを送信する前に、受信者の安全に関する状態に反映しなければなりません。イベントの台帳は追記のみとし、ユーザーに見せるステータスは明示的なルールで導出してください。そうすれば、サポートは証拠と解釈を区別できます。

失敗、苦情、配信停止を送信時に適用する

Mailgunは、配信の失敗、迷惑メール報告、配信停止のトラッキングを文書化しています。これらのシグナルを、テナント、アドレス、メッセージの種類、発生元のイベント、理由、有効となる時刻を含む、プロダクトが所有する受信者の安全モデルに取り込んでください。その状態は、キャンペーンのリストをインポートするときだけでなく、各送信の直前に確認します。恒久的なバウンスや苦情があれば、該当する範囲での安全でない再試行を止めるべきです。配信停止の処理は、メッセージの種類と、現在の受信側や法的な要件を尊重しなければならず、プロバイダーのオプションを使って日常的に回避すべきではありません。手動での解除は、強い認可、明示された理由、監査履歴で保護してください。プロバイダーのサプレッションのデータは運用上の貴重な証拠ですが、完全な同意の台帳ではありません。移行によって受信者の保護が失われないよう、同意の取得元、配信設定、プロダクトにとって重要なポリシーの判断、過去のプロバイダーの履歴は別々に保持します。サプレッションの伝播、重複した苦情、遅延バウンス、例外的な再有効化を、管理されたIDでテストしてください。

Mailgunの代替としてSendHQを検討する

SendHQは、検証済みドメイン送信、メール受信、配信イベント、サプレッションを備えたトランザクションメールと同意に基づくマーケティングメールを提供します。移行前に公開APIドキュメントを確認し、認証、ペイロード、エラー、ID、イベント、ドメイン、受信者の安全性を確保するワークフローをテストしてください。

よくある質問

出典

• Mailgun Messages API — Mailgun
• Mailgun APIの認証 — Mailgun
• Mailgunのドメインを検証する — Mailgun
• Mailgunのイベントの種類 — Mailgun
• MailgunのWebhookを保護する — Mailgun
• MailgunのWebhookの再送 — Mailgun
• Mailgunの配信失敗のトラッキング — Mailgun
• Mailgunの迷惑メール報告のトラッキング — Mailgun
• Mailgunの配信停止のトラッキング — Mailgun
• RFC 5321：簡易メール転送プロトコル（SMTP） — RFC Editor
• SendHQ OpenAPI仕様 — SendHQ