testing-with-sandbox

Mailtrap Email Sandbox でのテスト

概要

Email Sandbox は、サンドボックス（テスト用受信トレイ）でメールを受信します。これは、メッセージが実際の受信者に配信されないテスト環境です。ニーズに応じて、SDK、HTTP API、またはSMTPを使ってサンドボックスに送信できます。

SDK コードを生成する前に： 該当する SDK リポジトリ（sending-emails を参照）の README を読み、現在のサンドボックスモードのオプション、inbox id、コンストラクターのフラグを確認してください。記憶に頼らないでください。

関連スキル： authorizing-api-requests（サンドボックスのトークンのスコープ、環境変数、account_id の解決）、sending-emails（本番送信のホストとストリーム）、using-email-templates（サンドボックスでのテンプレート送信のプレビュー）。

使用する場合

• 実際には配信しない場合：メールをテスト用受信トレイに留めておく必要がある開発、ステージング、CI、デモ。
• Sandbox / Testing API または UI を使って、送信内容（本文、ヘッダー、添付ファイル、スパムレポートなどの基本的なチェック）を確認する必要がある場合。
• 受信したメールを対象にテストを自動化する場合。
• 既存のアプリからサンドボックスに送信するため、SMTP 設定のみを変更する場合。このスキルではフレームワークごとのチュートリアルは必要ありません。

使用しない場合

• 実際の受信者への本番送信（sending-emails）。
• フレームワークの完全な設定ガイドや詳細な API リファレンスが必要な場合は、SMTP/API の詳細については Mailtrap の Integration タブを、詳細については API docs を案内してください。ここでは、すべてのフレームワークや API フィールドを網羅しないでください。

クイックリファレンス

API のベース URL

サービス	メール送信 URL	認証ヘッダーの例
Email Testing API (REST)	https://sandbox.api.mailtrap.io/api/send/{inbox_id}	Authorization: Bearer $MAILTRAP_SANDBOX_API_TOKEN

トークンと account_id

Sandbox では別のトークン（$MAILTRAP_SANDBOX_API_TOKEN、Testing/Sandbox スコープ）を使用します。本番用の $MAILTRAP_API_TOKEN を再利用しないでください。以下のエンドポイント例での account_id は、実行時に GET https://mailtrap.io/api/accounts を使って解決されます。トークンのスコープ、保存、account_id の解決について詳しくは、スキル authorizing-api-requests を参照してください。

API と SMTP の使い分け

SMTP 経由で既にメールを送信しているアプリをテストする場合は、SMTP を使用します（ホスト、ポート、認証情報を更新するだけです）。 新しい連携を構築する場合や、アプリから HTTP リクエストを送信できる場合は、HTTP API を使用します。プログラムによるテストや自動化に適しています。

SMTP 設定（サンドボックス）

設定	値
ホスト	sandbox.smtp.mailtrap.io
ポート	2525（デフォルト）、25、465（SSL）、587
ユーザー名 / パスワード	Mailtrap UI の Integration タブにあるサンドボックス用認証情報

本番環境でサンドボックスの認証情報やエンドポイントを使用しないでください。メッセージはサンドボックスにのみ取り込まれ、配信されません。

主なパラメーター

• Inbox ID：各サンドボックス（テスト用受信トレイ）には固有の inbox id があり、UI の URL で確認できます。送信や REST API 操作に必要です。
• トークンのスコープ：対象のプロジェクトとテスト用受信トレイに対する権限を持つトークンを使用してください。

主な用途

• 開発、テスト、ステージングで、送信メールをすべて取り込む（実際の受信者には配信しない）。
• メッセージのヘッダー、本文、HTML、添付ファイル、スパムスコアを表示、検証、アサートする。
• Email Sandbox API からデータを読み取る統合テストや CI チェックを実行する。
• 有効な inbox id を指定し、API または SDK/SMTP の送信先を sandbox.api.mailtrap.io / sandbox.smtp.mailtrap.io に設定して、Mailtrap テンプレートをテストする。

API パスの例

詳細についてはAPI ドキュメントをご覧ください。一般的なエンドポイントは次のとおりです。

操作	URL	リファレンス
サンドボックスの一覧表示	GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes	Sandboxes API
メッセージの一覧表示	GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages	Messages
メッセージの取得	GET https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages/{id}	Message details
テストメールの送信	POST https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/inboxes/{inbox_id}/messages	Send test emails

テンプレートのテストについては、テンプレートの Integration タブと Handlebarsをご覧ください。

SDK

公式の Mailtrap SDK はサンドボックス／受信トレイの操作に対応しており、テストモードと受信トレイ IDを設定するフラグやメソッドを利用できます。これにより、同じインテグレーションを実際の送信とサンドボックスでのテストの両方に使用できます。環境（開発、ステージング、本番）に応じてモードまたは認証情報を変更するだけです。インストールコマンドと言語の対応状況については、Mailtrap 開発者向けドキュメントをご覧ください。最新のサンドボックス設定については、各リポジトリの README をご確認ください。

• Node.js
• Python
• PHP
• Ruby
• Java
• .NET
• CLI

よくある間違い

間違い	修正／説明
サンドボックスから実際にメールが配信されると思い込む	サンドボックス内のメールは、宛先に配信されることはありません
サンドボックスに本番用 API トークンを使用する	対象の受信トレイへのアクセスを許可する、適切なサンドボックス／テストスコープのトークンを使用してください
受信トレイ IDパラメーターを忘れる	メッセージを正しい受信トレイに関連付けるため、必ず（UI または Integration タブにある）受信トレイ IDを指定してください
サンドボックスとトランザクション用エンドポイントを混同する	テスト API（sandbox.api.mailtrap.io）は、send.api.mailtrap.io（実際の送信）とは異なります！

サンドボックスのメールアドレス

各サンドボックス（テスト用受信トレイ）には、受信テスト用の [email protected] のようなアドレスがあります。プラスアドレスを使うと、シナリオを分けやすくなります。制限と動作については、サンドボックスごとのメールアドレスをご覧ください。