プロダクトチームはPostmark APIをどう安全に実装すべきですか？

Postmarkの前にアプリケーションの境界を定義する

領収書、確認、要求されたアラート、セキュリティ通知など、認可された業務イベントから始めます。安定したイベントキー、テナント、メッセージの種類、テンプレートのリビジョン、承認された送信者と受信者、同意または必要性の根拠、現時点でのサプレッションの判定、初期状態を持つ永続的な送信ジョブを保存してください。ブラウザ、モバイル、テンプレート、ユーザーの入力によって、Postmarkのサーバートークン、任意のFromのID、メッセージストリーム、Webhook、制限のない受信者、プロバイダーのメタデータを選択できてはいけません。プロバイダーの呼び出しはすべて、サーバー側の1つのアダプターの背後にまとめます。トランザクションのトラフィックと、ブロードキャストやマーケティングのトラフィックは、プロダクトの同意とレピュテーションのモデルに従って分けてください。PostmarkのAPIはメッセージを転送するものであり、テナントの認可、受信者の同意、業務上の冪等性を確立するものではありません。内部のジョブは一度だけ取得し、プロバイダーへのすべての試行を記録し、プロバイダーの識別子は唯一の記録として使うのではなく、アプリケーションのイベントに紐付いた証拠として保持しましょう。

運用範囲を狭く絞ったサーバートークンを使う

PostmarkのメールAPIでは、サーバー単位のAPIアクセスのためにX-Postmark-Server-Tokenヘッダーが記載されています。各トークンは管理されたシークレットサービスに保存し、そのサーバーと環境を必要とするワーカーにだけ公開します。トークンをクライアントのコード、ソース管理、URL、ログ、アナリティクス、テンプレート、スクリーンショット、チケット、プロンプト、テスト用のデータに含めてはいけません。失効や不正使用の影響を限定できるよう、本番と開発、無関係なプロダクトは分けてください。ローテーションは、承認された管理手順で代替トークンを発行し、ワーカーを更新し、管理されたメッセージを送信し、APIとイベントの証拠を確認してから古いトークンを失効させる、という流れでリハーサルしておきます。予期しない認証エラーは、認証情報をすばやく再試行する合図ではなく、一時停止すべき状況として扱ってください。ダッシュボードの管理は、強力な認証とロールで制限します。サーバートークンはそのサーバーに対するPostmark APIの操作を許可するものであり、テナント、送信者、受信者、テンプレート、メッセージの種類の認可は引き続きアプリケーションが行う必要があります。

正確な送信者IDを検証する

組織が管理する送信者署名または検証済みドメインを使い、各ストリームで使われる正確なFromアドレスを確認します。実際に受信したサンプルで、表示上のFromドメイン、SMTPのリターンパス、DKIMのd=ドメインとセレクター、返信先アドレス、送信に使うメッセージストリームを洗い出してください。既存のSPF、DKIM、DMARCの管理状況を確認したうえで、選択した構成でPostmarkが現在必要とするDNSレコードだけを公開します。以前の値とロールバックの手順は保存しておきましょう。プロバイダーでの検証は、その設定チェックに合格したことの証拠です。すべてのアプリケーションの経路がそのIDを使っていること、DMARCがアライメントしていること、受信者が同意していること、メッセージが受信トレイに届くことまでは証明しません。テナントごとの送信者の認可はアプリケーション側で管理し、テナントをまたいだFromの値はブロックしてください。サブドメイン、返信、バウンス、下位環境、テンプレートの経路をテストします。ダッシュボードの表示を緑にするためだけに、組織のSPFやDMARCのポリシーを緩めてはいけません。

明示的なPOST /emailリクエストを1つ組み立てる

Postmarkのドキュメントでは、POST /emailのJSONフィールドとして、送信者、受信者、件名、テキストまたはHTMLの本文、ReplyTo、ヘッダー、タグやメタデータ、メッセージストリーム、添付ファイル、トラッキングのオプションが記載されています。公開するのはプロダクトが必要とするフィールドだけにしましょう。アドレスを検証して正規化し、受信者数と添付ファイル数に上限を設け、ヘッダーインジェクションを拒否し、テンプレートの値は出力のコンテキストに応じてエスケープし、テキストとHTMLは承認済みの1つのリビジョンから生成します。タグ、メタデータ、ヘッダー、件名、添付ファイル名は、プロバイダーのアクティビティやイベントに表示されることがあるため、秘密情報や不要な個人データを入れないでください。MessageStreamは、任意のリクエスト入力からではなく、信頼できる設定から選びます。業務コードがPostmarkのすべてのフィールドに依存しないよう、プロバイダーのペイロードは1つのアダプターにまとめましょう。監査上の必要がある場合は、メッセージ本文全体をログに残すのではなく、コンテンツのリビジョンやプライバシーに配慮したハッシュを保存してください。

直後のレスポンスは限定的に解釈する

Postmarkの単一メール送信エンドポイントでは、ErrorCode、Message、MessageID、SubmittedAt、受信者情報などのレスポンスフィールドが記載されています。正確なHTTPステータスと構造化されたプロバイダーのレスポンスを、アプリケーションの送信試行とともに保存してください。成功のレスポンスとMessageIDは、ドキュメントに記載された意味の範囲で、PostmarkがAPIリクエストを受け付けたことを示します。宛先サーバーがメッセージを受け付けたことや、受信トレイに届いたことを示すものではありません。再試行の前に、バリデーション、送信者署名、認証、不正な形式のペイロード、クォータ、ポリシーのエラーを分類します。リクエストのタイムアウトは結果があいまいです。Postmarkが操作を受け付けていたのに、クライアントがレスポンスを受け取れなかった可能性があるからです。その試行は不明の状態のままにし、安全な相関データを使ってプロバイダーのアクティビティや後から届くイベントを探し、再送の前にメッセージの種類ごとの突き合わせルールを適用してください。HTTPリクエストが1回失敗したというだけで、Exactly-Onceの配信を約束したり、新たな論理イベントを作成したりしてはいけません。

プロバイダーと転送の証拠に基づいて再試行を設計する

再試行するのは、対象となるネットワーク障害、レート制限、プロバイダーのサーバーエラーだけにし、指数バックオフ、ジッター、有限の試行回数、キューの滞留時間の上限を設けます。リクエスト、送信者、受信者、トークン、テンプレート、ポリシーに関する恒久的なエラーは、再実行するのではなく修正してください。同じアプリケーションのイベントキーを保ち、関連する試行を記録します。キューで待っている間に受信者や業務の状態が変わることがあるため、再試行の直前にはサプレッションと認可を再確認してください。1つの障害が容量を独占しないよう、サーバー、テナント、メッセージストリーム、送信ドメイン、宛先のコホートごとに同時実行数とレートを制限します。イベントの期限切れ、送信者IDの失効、苦情、配信停止、受信者の恒久的な失敗、インシデントによる一時停止の場合は停止してください。再試行の滞留時間、結果が不明の件数、レスポンスの分類、トークンの失敗、プロバイダーのレイテンシーを監視します。受け付け後にPostmarkがすでに後段のSMTP再試行を行っている場合、その転送の挙動の上に、アプリケーション側で積極的に重複を生むループを作ってはいけません。

配信とバウンスのWebhookを保護する

アプリケーションが必要とするPostmarkのWebhookの種類だけを設定し、HTTPSを使います。現行のドキュメントに記載されたWebhookのセキュリティ対策を適用し、エンドポイントを想定されるサーバーやストリームに限定し、リクエストのサイズとContent-Typeに制限を設けてください。JSONとしてパースできたというだけで、メッセージ識別子、受信者、タグ、メタデータ、診断情報を信頼してはいけません。成功を返す前に、認証済み、あるいは安全に受け入れたイベントを永続化するかキューに入れます。重複の排除には、可能であればプロバイダーの安定したイベント識別子を使い、なければ受信者、イベントの種類、試行を混同しない慎重な複合キーを使ってください。発生時刻と処理時刻は別々に保持します。遅延、再試行、重複、順序の入れ替わりは起きるものと想定しましょう。状態を変更する前に、MessageIDと信頼できるメタデータを内部のテナントとジョブに関連付けます。WebhookのURLや認証情報はAPIトークンとは独立してローテーションし、認可されていないリクエストと遅延を監視し、生のペイロードは運用上とポリシー上の必要性がある期間だけ保持してください。

配信、バウンス、サプレッションの状態をモデル化する

Postmarkの配信とバウンスの証拠を、受信者単位の内部モデルに対応付けます。その際、プロバイダーの元のイベントの種類、MessageID、タイムスタンプ、ステータスやバウンスの分類、診断情報は保持しておきます。APIによる受け付け、Postmarkでの処理、宛先サーバーによる受け付け、後からの不達、メールボックスのフォルダへの振り分け、エンゲージメントは、それぞれ異なる状態です。配信済みイベントは通常、ドキュメントに記載されたとおりプロバイダーが宛先サーバーで観察した内容を反映したものであり、最終的なフォルダを示すものではありません。一時的な失敗には上限付きの転送処理で対応できる場合がありますが、確認された恒久的なアドレスの失敗には、受信者単位のサプレッションを作成するべきです。苦情と配信停止は、以後のジョブより前に受信者の安全に関する状態へ反映しなければなりません。手動での再有効化は、認可、理由、監査履歴で保護してください。移行によって受信者の保護が失われないよう、同意とサプレッションの状態はプロダクト側で管理します。開封やクリックのトラッキングはエンゲージメントの計測であり、プライバシー保護技術の影響を受けることもあるため、そこから人が読んだと推測してはいけません。

サンドボックス、本番、失敗時の経路をテストする

決定的な失敗のテストには、実際の顧客のアドレスではなく、Postmarkのドキュメントに記載されたテストやサンドボックスの機能と、専用の管理された受信者を使います。有効なトークンと無効なトークン、認可されていないFromのID、承認された受信者とブロックされた受信者、テキストとHTML、Unicode、添付ファイル、メタデータの最小化、メッセージストリーム、受け付けの前後でのリクエストタイムアウト、レート制限のレスポンス、Webhookの認証、重複配信、順序の入れ替わったイベント、バウンスの分類、サプレッション、トークンのローテーションをテストしてください。実際に受信したヘッダー、DKIMとDMARCのアライメント、Reply-To、トラッキングの設定、MessageIDの関連付けを確認します。下位環境から本番の受信者に届かないことも確認しましょう。サプレッションと運用上の証拠について、エクスポートと移行のテストを実施します。テナントをまたいだ送信者やイベントへのアクセス、サプレッションを強制できない、Webhookの受け入れがあいまい、ログに秘密情報がある、再試行に上限がない、影響を受けたサーバーやストリームを安全に一時停止できない、といった場合はリリースを止めてください。

SendHQの位置付け

SendHQは、想定されたプロダクトコミュニケーション向けのワークスペース単位のメールAPIです。公開ドキュメントでは、検証済みドメイン送信、メール受信、ホスト型テンプレート、配信イベント、サプレッション、Webダッシュボードを扱っています。

よくある質問

出典

• Postmark Email API — Postmark
• Postmark APIの概要 — Postmark
• Postmark Webhookの概要 — Postmark
• PostmarkのバウンスWebhook — Postmark
• RFC 5321：簡易メール転送プロトコル（SMTP） — RFC Editor