PHPアプリのメールプロバイダーを変更する作業は、認証情報を別のものに置き換えるだけではありません。送信方式によって、送信者、添付ファイル、テンプレート、送信制限、エラー時の応答の設定方法が変わることがあります。アプリがこうした判断を業務ロジックと混在させていると、移行によってメールが重複したり、状態が不明瞭になったり、明確な兆候がないまま通知が送信されなくなったりするおそれがあります。
実務上の目標は、アプリが「何を」伝えるかを決め、プロバイダーがメッセージを「どのように」送信するかを担うことです。この分離により、新しいサービスをテストし、運用上の参照情報を保持し、検証可能な基準に基づいて切り替えられます。ただし、メールが受信トレイに届くことを保証するものではありません。外部サービスによる受け付けは、配信、開封、あるいはその後にフィルタリングされないことを意味しません。
連携に手を加える前にメールを棚卸しする
チームが把握しているものだけでなく、すべてのメール送信フローを特定することから始めます。コード内の送信処理の呼び出しを検索し、バックグラウンドタスク、スケジュール実行されるコマンド、管理プロセス、アプリを呼び出す可能性のある外部サービスを確認します。見つかった項目を設定や利用可能なログと照合します。
メッセージの種類ごとに、次の項目を記録します。
- 発生元と目的：どの処理が生成し、操作の確認や障害の通知など、何を達成しようとしているか。
- 優先度と期限：即時に処理する必要があるか、非同期タスクに回せるか。
- 宛先と必要なデータ：誰が受信し、メッセージの作成にどの情報が必要か。
- 形式と制約：テキスト、HTML、添付ファイル、送信者、返信先、形式やサイズの要件。
- 障害時の動作：再試行するか、保留するか、担当者に通知するか、キャンセルするか。
この分類により、重要な通知と情報提供のメッセージを同じように扱わずに済みます。また、削除済みのデータを使うテンプレートや、無期限に再試行するタスクなど、移行中に見落とされがちな依存関係も明らかになります。
業務上の判断と送信処理を分離する
業務ロジックは、たとえば確認メールの送信を要求するなど、意図を表現するべきです。外部API固有の詳細を把握したり、プロバイダー固有のヘッダーを組み立てたりするべきではありません。アプリの実際のニーズに合った内部契約を定義し、具体的な連携処理をアダプターの背後に置きます。
PHPでは、小さなインターフェースを使って境界を明確にできます。
interface MailTransport
{
public function send(OutboundMessage $message): TransportResult;
}OutboundMessageには、送信者、宛先、件名、本文、許可されたメタデータを表現できます。TransportResultでは、少なくとも送信処理による受け付けと既知のエラーを区別します。リクエストが受け付けられただけのメッセージを「配信済み」と呼ぶのは避けてください。状態は、実際に把握できていることを表す必要があります。
アダプターは、内部契約を選択したサービスが要求する形式に変換します。認証情報、送信者、エンドポイント、オプションなどの設定はコードの外に置き、環境ごとに管理して、シークレットを保護します。複数のプロバイダーがある場合は、業務ロジックのあちこちに条件分岐を置くのではなく、明確な設定によってアダプターを選択します。管理を委ねる具体的な理由がない限り、テンプレートと通知ポリシーは送信処理から分離しておきます。
インターフェースを用意しても、サービス間の違いがすべてなくなるわけではありません。サイズ制限、添付ファイル、エラーコード、高度な機能は同等でない可能性があります。共通の機能と固有の機能を文書化し、専用機能が不可欠か、切り替え前に別の方法へ置き換えるべきかを判断します。
状態と役立つ参照情報を保持する
追跡性を確保するには、送信要求と、それを発生させた処理を関連付けます。ただし、ログをメールの複製にしてはいけません。メッセージに内部識別子を割り当て、請求書や申請など、元となったエンティティまたはイベントへの参照を保持します。プロバイダーからメッセージIDが返された場合は、内部識別子の代わりにせず、関連付けられた外部参照として保存します。
運用上の疑問に答えられるよう、送信要求の日時、試行日時、試行回数、アダプターが返した結果、後続の応答が確認できるかなどの状態遷移を記録します。たとえば、保留中、送信処理で受け付け済み、拒否、一時的な失敗など、意味が明確な状態を定義します。裏付けとなる検証可能な通知がない場合、配信状態を作り出してはいけません。
記録するデータは最小限にします。本文、添付ファイル、メールアドレス、個人データは機微情報である可能性があり、送信障害の診断には通常必要ありません。エラーコードやメッセージは慎重に保存し、アクセスを管理して、保持ポリシーを定めます。外部イベントやWebhookを受信する場合は、真正性を検証し、同じ通知を繰り返し処理しないようにします。
実際のメッセージを重複させずに新サービスをテストする
切り替え前に、管理された環境で認証情報、許可された送信者、形式、添付ファイル、エラー処理などの設定を検証します。棚卸しした各カテゴリの代表的なフローをテストし、一時的な障害、拒否応答、保留中タスクの復旧も確認します。ログに内部参照が保持され、エラーにシークレットが含まれないことを確かめます。
並行テストには特に注意が必要です。同じイベントを両方のプロバイダーに実際の宛先で送ると、重複メールが発生する可能性があります。代わりに、2回目の送信を行わずにメッセージ生成結果を比較する、管理されたテスト用宛先を使う、サービスが対応していればテスト環境に対してリクエストを検証する、といった方法を使います。テストモードが本番環境のすべての条件を再現するとは限りません。
実際の送信を比較する場合は、対象とするメッセージ、受信できる人、同じ処理の重複を防ぐ方法を事前に定めます。アプリと送信処理が対応していれば、冪等性キーは重複した要求の識別に役立つことがあります。ただし、キューの設計に代わるものではなく、それだけで重複がなくなる保証もありません。旧プロバイダーと新プロバイダーで、制限やポリシーが異なるかどうかも確認します。
切り替えとロールバックの基準を定める
切り替えは、アプリが起動したというだけで決めず、観測可能な指標に基づいて判断します。どのフローから有効化するか、誰が次の段階への移行を承認するか、どの指標を確認するかを合意します。指標には、接続エラー、拒否、保留中メッセージの滞留時間、タスクの処理時間、確認可能な外部応答などがあります。配信と受け付けを混同せず、各フローの量とリスクに応じたしきい値を定めます。
旧送信方式に戻す方法をあらかじめ決めます。旧設定を一時的に安全に保持し、アプリのバージョンで旧方式を選択できることを検証します。切り替え中にキューに残ったメッセージの扱いも決めておきます。処理を一時停止して再開するのか、送信経路を一つに限定するのか、再試行前に分類するのかを定めます。プロバイダーを切り替えても、旧システムがすでに受け付けた送信は取り消されません。確認せずに再送すると、メッセージが重複する可能性があります。
ロールバックしても、すでに送信されたメールを取り戻したり、受信者や外部システムの判断を取り消したりすることはできません。ロールバックの目的は、運用可能な送信経路を復旧し、明示したルールに従って保留中のものを処理することに限られます。どの要求が受け付けられ、どれが失敗し、どれに確認が必要かを説明できるよう、移行の記録を保持します。
移行チェックリスト
- メッセージの種類、発生元、優先度、宛先、依存関係を棚卸しする。
- 内部契約、アダプター、環境ごとの設定を定義する。
- 内部識別子を割り当て、配信を保証するかのような状態名を避けて状態を定義する。
- プライバシー、アクセス、保持期間、ログの内容を確認する。
- 実際の宛先に重複送信せず、形式、エラー、再試行、代表的なタスクをテストする。
- 担当者、進行を判断する指標、切り替え条件、ロールバック手順を定める。
- 最初の送信を監視し、旧連携への依存関係や対応が必要な保留中メッセージがなくなってから、旧連携を廃止する。
チームが、どのメッセージが要求され、何回試行され、各送信処理が何を確認し、何がまだ不明なのかを説明できれば、移行を管理できています。この明確さに、小さな技術的境界と検証済みの切り替え計画を組み合わせることで、外部システムに依存する保証をアプリ自身が提供するかのように扱わずに、プロバイダーを変更するリスクを減らせます。
