使い方 · 2026
2026 Mailgun Inbox Placement Test APIをCIにどう接続する?
自社製品のメール送信をCIで検証する開発者、QA担当者、個人開発者向けの記事です。Send APIへのテストキーの付け方、再試行時の扱い、レポートの読み方を時間軸に沿って整理し、種子テストと実際の受信確認を分けて説明します。
2026 Mailgun Inbox Placement Test APIをCIにどう接続する?自社製品のメール送信をCIで検証する開発者、QA担当者、個人開発者向けの記事です。Send APIへのテストキーの付け方、再試行時の扱い、レポートの読み方を時間軸に沿って整理し、種子テストと実際の受信確認を分けて説明します。
この記事の目次
Mailgun Inbox Placement Test APIをCIに接続するなら、アカウントでInbox Placementが有効か確認したうえで、通常のSend APIリクエストにo:inbox-placement-test-keyを追加してください。同じテスト実行の再試行では同じキーを使い、種子リストのレポートと、テスト用メールボックスでの実受信・リンク動作確認は別々に判定します。
CIの送信処理を管理し、Mailgun Send APIの応答と受信位置レポートを紐づけたい開発者向けです。
種子テストの結果を、ユーザーがメールを受け取った証拠と混同したくないQA担当者にも役立ちます。
同じワークフローの再実行で不要なテストを増やしたくない個人開発者も対象です。
最終更新:2026年11月20日。確認資料は、Send APIのパラメーター仕様、Send APIからInbox Placementテストを実行する公式手順、種子テストのガイドです。公開前にも仕様変更がないか確認してください。
CIで何を証明するか、最初に切り分ける
「メール機能をテストする」といっても、確認対象は同じではありません。アプリケーションの送信処理が正しく呼ばれたか、種子リストでどの受信位置になったか、実際に管理下の受信箱へメールが届いてリンクを使えるかは、それぞれ異なる証拠です。
| 検証したいこと | 主な確認方法 | 成功しても証明できないこと |
|---|---|---|
| アプリのメール生成・送信処理 | CIログとSend API応答 | 種子リストでの受信位置、実ユーザーの受信 |
| 種子環境での受信位置 | Inbox Placementレポート | 自社の登録フローや実受信箱での動作 |
| 自社製品のメールの実受信と業務フロー | 管理下のテスト用メールボックスで受信・リンク確認 | すべての受信事業者での受信位置 |
Inbox Placementが有効で、かつ自社製品または送信許可を得た環境をテストする場合は、通常の送信リクエストに専用パラメーターを加える方法が使えます。これは種子テストを関連づける仕組みであり、個々の受信者の受信箱に入ることを保証するものではありません。詳細はSend API経由の公式実行手順で確認できます。
接続前の確認項目
- 対象アカウントでInbox Placementが利用可能になっているか確認します。
- 送信元、宛先、メール本文が、自社製品または許可を得たテスト環境のものか確認します。
- CIが保存する識別子と、レポートを確認する担当者を決めます。
- Send APIの正常応答、レポート生成、テスト用受信箱での確認を別の判定項目にします。
送信実行にテストキーを関連づける
o:inbox-placement-test-keyは、通常のSend APIリクエストと一緒に送るパラメーターです。API仕様に従ってキーを設定すると、その送信はInbox Placementテストに関連づけられ、テストに対応する種子リストへテスト用メールが送られます。キーやリクエスト形式は、Send APIパラメーターの公式リファレンスを正としてください。
| 設定・記録項目 | CIでの扱い | 判定時の注意 |
|---|---|---|
o:inbox-placement-test-key |
同一テスト実行の再試行では同じ値を送信 | 送信のたびに無条件で新しい値を作らない |
| 実行識別子 | ビルドやテスト実行とキーの対応を記録 | キーをログや公開成果物に不用意に露出させない |
| Send API応答 | 応答と実行識別子を保存 | 受信位置レポートの完成とは別に扱う |
| Inbox Placementレポート | 対象キーと対応づけて確認 | 種子リストの結果を実ユーザーの受信保証にしない |
実装では、メール送信のコードパスをテスト用に置き換えるのではなく、自社製品が通常使う送信処理にテストキーを追加します。そうすれば、本文生成や宛先設定を含む送信経路を保ったまま、対象の実行を種子テストに関連づけられます。
CIの記録には、テスト実行の識別子、キー、Send APIの応答、レポート確認結果をまとめて残します。ただし、ログに認証情報や実在ユーザーの個人情報を出さないようにしてください。メール本文や検証リンクも、テスト環境用の値に限定します。
同一キーの再試行と新しい実行
CIでは、一時的な通信障害による再送と、テスト担当者が別の結果を得るために始める新しい実行を区別します。公式資料では、同一のキーを7日以内に再利用しても新しいテストは作成されず、アカウントに保存できるキー数にも上限があります。保存上限は10個と案内されています。実装時には、Send API経由の実行説明で最新の制約を再確認してください。
| 状況 | キーの扱い | CIの動作 |
|---|---|---|
| 同じ実行のネットワーク再試行 | 同じキーを再利用 | 既存のテストに紐づく結果を確認 |
| 意図した新しいテスト実行 | 新しいキーを発行 | 新しい実行識別子とともに記録 |
| キー上限に達した可能性がある | 追加発行を急がない | 保存済みキーやアカウント状態を確認 |
同じキーを使う利点は、リクエストの再試行を新しいテストの作成と混同しにくいことです。一方、新しいレポートが必要なのに前回と同じキーを使えば、期待した新規テストが作成されない可能性があります。逆に、ネットワークの再試行ごとに新しいキーを割り当てる設計では、意図しない重複テストやキー消費につながります。
キーの生成タイミングは、メール送信のたびではなく、独立したテスト実行の開始時に合わせます。同じジョブ内の再試行では保存済みのキーを読み戻し、別の実行として扱う場合だけ新しいキーを発行してください。
レポート未生成時に確認する順序
レポートが見つからない場合、まず「送信が失敗した」と決めつけず、リクエストから種子側の処理までを順に追います。特に、キーを以前の実行で使っていないか、保存キーの上限に達していないか、種子リストへの送信が完了しているかを確認します。
| 確認順 | 証拠 | 次に行うこと |
|---|---|---|
| 1 | CIのリクエスト記録にキーがあるか | パラメーター名、値、送信先の環境を照合 |
| 2 | 同じキーの過去の利用記録 | 再利用なら、新規レポートではなく既存テストを確認 |
| 3 | アカウントの保存キー状況 | 上限の可能性があれば、公式手順に沿って状態を確認 |
| 4 | Send API応答と種子送信の進行状況 | リクエスト受付と種子への配信完了を分けて記録 |
| 5 | Inbox Placementレポートの状態 | Missingの定義と判定時点を公式ガイドで照合 |
種子一覧にMissingと表示されても、それだけでメールが確実に消失したとは判断できません。種子側でまだ受信していない状態と、アプリケーションが送信していない状態は別です。種子ガイドに示される待機・判定条件を確認してから失敗扱いにし、待機中の結果をCIの最終エラーとして即時に固定しない設計にします。
確認時は、同じキーの過去の実行、Send API応答、レポートの状態を一続きの記録として並べてください。レポートが後から利用可能になる場合に備え、送信ジョブのログだけで終了させず、レポートを確認する処理とタイムアウト時の扱いも別途定義します。
時系列の証拠で受け入れ判定する
種子レポートの確認後も、登録メールやパスワード再設定メールが自社の利用者向けフローで正しく働くかは別途検証します。Inbox Placementの結果は、そのテスト設定と種子環境で観測した結果です。自社のアプリケーションが生成した検証リンク、アカウント状態の更新、リンク利用後の画面遷移までは証明しません。
| 時点 | CIまたはテストで残す証拠 | 判定できる内容 |
|---|---|---|
| リクエスト作成 | 実行識別子、使用キー、対象環境 | テストが意図した設定で開始されたか |
| Send API応答 | 応答内容と記録時刻 | リクエストが受け付けられたか |
| レポート確認 | キーに対応する種子結果と状態 | テスト設定内の種子でどう観測されたか |
| 管理下の受信確認 | 受信メール、リンク先、処理後の状態 | 自社製品の実受信と業務フローが動くか |
Mailgun Inbox Placement Test APIのCI接続手順
- テスト対象を決めます。登録、パスワード再設定、通知など、どの自社製品のメールを検証するかを明記します。
- アカウントでInbox Placementが有効か確認し、テスト環境と送信権限を点検します。
- CIの独立したテスト実行ごとにキーを用意し、同一実行の再試行ではキーを再利用する実装にします。
- アプリケーションの通常のSend APIリクエストに
o:inbox-placement-test-keyを加え、応答と実行識別子を保存します。 - 種子レポートが確認できたら、受信位置の結果を記録します。レポート未生成やMissingは、キーの再利用状況と種子への送信状況を調べてから判定します。
- 実際のユーザー向け機能まで受け入れる場合は、管理下のテスト用メールボックスでも受信し、検証リンクと処理後のアカウント状態を確認します。
受信箱を選ぶ際は、短期の使い捨てアドレスと継続利用するメールアドレスの違いも考慮してください。自社テストで一時的に受信する用途なら、一時メールとメールエイリアスの使い分けを確認し、テスト後もアカウントの復旧に使うアドレスなら、受信箱の利用期間を考えるためのガイドを参考に運用条件を決められます。
CIに必要なのが種子リストの受信位置だけなら、Inbox Placementレポートを使い、実メールの受信や業務フローまで受け入れるなら別の管理下アドレスで確認する、という分担が明確です。後者では、個人の主アドレスをテストデータに使わず、テスト用の受信先で内容とリンクを確認してください。Mailtockの一時メールは、登録を増やさずに受信先を用意したい検証の選択肢になります。種子テストとは切り離して、自社製品のメールが読める状態かを確かめる用途に限って活用してください。
この記事では買い物メールの管理方法を提案しています。店舗の注文、配信解除、プライバシー対応に関する案内の代わりにはなりません。具体的な手続き場所や処理期間は、各サービスのルールをご確認ください。