使い捨てメール API：開発者向けガイド

Web の受信トレイは人間には便利ですが、テストや自動化には使い捨てメール APIが必要です。つまり、使い捨てアドレスを作り、そこに届いたものを読み、最後に片付けるまでを、すべてコードから行う手段です。このガイドでは、その構成要素と、MoeMail の一時メール OpenAPI への組み込み方を順に見ていきます。

なぜ Web 受信トレイではなく API なのか？

登録、メール認証、パスワードリセットのフローは、E2E でテストするのがもっとも難しい部類です。認証のステップでいったんアプリの外に出て、受信トレイに着地するからです。使い捨てメール API はそのループを閉じます。テストが新しい受信トレイを払い出し、フローを起動し、API をポーリングして認証メッセージを取得し、リンクやコードを抽出する。これを、汚染しがちな人間共用のメールボックスなしで、決定的に行えます。

API キーによる認証

MoeMail はプログラムからのリクエストを、X-API-Key ヘッダーで送る API キーで認証します。サインイン後にプロフィールからキーを生成し、すべてのリクエストに付与します。キーはメール系と設定系のエンドポイントに限定され、アカウントの月次クォータの対象になります。秘密情報として扱い、漏洩したらローテーションしてください。

主な操作

• メールボックスを作成 — ランダムまたはカスタムの新しいアドレスを、指定した有効期限で要求する。
• メッセージ一覧を取得 — メールボックスをポーリングして新着メールを確認する。
• メッセージを読む — 1通のヘッダー、本文テキスト、HTML 本文を取得する。
• そのまま期限切れにする — 何もしなくても、メールボックスとメッセージは自動でクリーンアップされる。

最小限のポーリング呼び出しは、キーをヘッダーに乗せてメールのエンドポイントに送るだけです。例：curl -H "X-API-Key: YOUR_KEY" https://moemail.app/api/emails。正確なリクエストとレスポンスの形は OpenAPI 定義 に記載されています。

webhook：ポーリングをやめる

ポーリングでも動きますが、遅延が増え、リクエストを無駄にします。MoeMail はメッセージが届いた瞬間に webhook を発火できるので、テストやバックエンドはループせずに即座に反応できます。webhook は、テストハーネスが管理するエンドポイントに向け、ペイロードを検証し、メッセージが着地したらすぐ待機ステップを解決させます。ハンドラーは速く保ってください。数秒以内に応答すること。遅い応答や 2xx 以外の応答はリトライを引き起こします。

レート制限とクォータ

API 利用はアカウントの月次 OpenAPI クォータに計上されます。大規模なテストスイートでは、可能な範囲でアサーションをまたいで受信トレイを使い回し、ポーリングをまとめ、きついポーリングループより webhook を優先してください。もっと余裕が必要なら、上位ロールやショップのクォータで上限が上がります。あるいは自前のインスタンスを動かす手もあります（セルフホストとホスティング型の一時メール参照）。

テストでの組み立て方

Playwright、Cypress、Selenium のいずれを使っても、パターンは同じです。作成・ポーリング・取得の呼び出しを小さなヘルパー（フィクスチャやカスタムコマンド）にまとめ、テストの冒頭で受信トレイを払い出し、UI を認証ステップまで進め、ヘルパー経由でメッセージを待つ。実行ごとに専用のアドレスが手に入るので、テストは独立を保ち、並列実行しても安全です。

次のステップ

API ドキュメント全文を読み、プロフィールからキーを取得し、作成してポーリングする往復を1回試してみてください。次に E2E で自動化しましょう。メール認証テストの自動化 と webhook による受信メールの受け取り を参照。概念から知りたい方は 一時メールとは から、あるいはダッシュボードで メールボックスを作成 して API の返り値を確かめてみてください。