LaravelとMailpit APIでメール送信を自動テストする:宛先・件名・本文の確認
作成日:2026.11.18
LaravelからSMTPで送ったメールをMailpit APIで検索・取得し、宛先・件名・本文をPHPUnitで照合する方法を紹介します。メールFakeとの使い分け、識別値によるメールの取り違え防止、期限付きの受信待ち、APIエラーの切り分けも説明します。
目次
Mailpitへ送ったメールはWeb UIで確認できますが、毎回開いて宛先や本文を調べるのは少し手間です。今回は、LaravelからSMTPで送ったメールをMailpitのAPIで取得し、PHPUnitで自動確認してみます。
ポイントは、テストごとに異なる識別値を付けて、そのメールだけを探すことです。「最新の1通」を取得する方法では、別のテストが送ったメールを拾う可能性があります。
メールFakeとMailpitで確認する範囲
LaravelのMail::fake()は、実際のメール送信を止めて、送信対象になったMailableや宛先などを検証する機能です。本文の確認には、MailableのassertSeeInText()なども使えます。本文を調べたいという理由だけで、すべてのテストをSMTP経由にする必要はありません。
一方、SMTP接続から受信したメールの内容まで確認したい場合は、Mailpitへ実際に送ります。今回の流れは次の通りです。
Laravelのテスト
├─ SMTPで送信 → Mailpitが受信・保存
└─ HTTP APIで検索・取得 → 宛先・件名・本文を照合
このテストではMail::fake()を呼びません。また、MailpitのHTTP送信APIを使うとLaravelからのSMTP送信を確認できなくなるため、APIは受信結果の読み取りに使います。
前提と、確認用のMailpit
LaravelプロジェクトとPHPUnitが利用でき、tests/TestCase.phpがある状態を前提にします。Mailpitの導入は、Windows 11でMailpitを導入してLaravelのメール送信を確認する記事を参照してください。
ローカルで動かす場合は、PowerShellで次のように起動できます。普段の受信箱とは分け、確認専用のMailpitを使ってください。
mailpit --listen 127.0.0.1:8025 --smtp 127.0.0.1:1025
今回はデータベースの保存先を指定せず、一時的な受信箱として使います。すでに同じポートで起動している場合は、重複して起動せず、専用のポートへ変更してください。SMTPの外部リレーや転送は設定しません。
以降のコードは、SMTPが127.0.0.1:1025、HTTP APIがhttp://127.0.0.1:8025の、認証を設定していないローカル環境向けです。Docker内から接続する場合は、127.0.0.1ではなくMailpitのサービス名を指定します。
Mailpit APIの基本
今回使うのは、次の2つのGET APIです。
| API | 用途 |
|---|---|
/api/v1/search?query=検索条件 | 条件に合うメールを検索する |
/api/v1/message/{ID} | 検索結果のIDから本文などの詳細を取得する |
検索条件にはsubject:"件名"を使えます。検索レスポンスのmessages_countが該当件数、messagesがメールの概要一覧です。totalは受信箱全体の件数なので、未着や重複の判定には使いません。その中のIDを詳細APIへ渡します。
検索は完全一致の保証として使わず、取得したメールの件名もPHP側で照合します。今回はランダムな識別値を件名に含めるため、過去のメールや他のテストと区別できます。仕様の詳細はMailpitのAPI資料と検索条件の説明を参照してください。
SMTP送信から受信内容の照合までをテストする
tests/Feature/MailpitTest.phpを作成し、次のように記述します。既存のアプリケーションのSMTP設定を上書きしないよう、テスト内で専用のmailpit_testメーラーを定義しています。
<?php
namespace Tests\Feature;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Mail;
use PHPUnit\Framework\Attributes\Group;
use Tests\TestCase;
#[Group('mailpit')]
class MailpitTest extends TestCase
{
public function test_smtp_mail_is_received(): void
{
config()->set('mail.mailers.mailpit_test', [
'transport' => 'smtp',
'scheme' => 'smtp',
'host' => env('MAILPIT_SMTP_HOST', '127.0.0.1'),
'port' => (int) env('MAILPIT_SMTP_PORT', 1025),
'username' => null,
'password' => null,
'timeout' => 3,
]);
$token = bin2hex(random_bytes(16));
$recipient = 'receiver@example.test';
$subject = 'mailpit-test-' . $token;
$body = '受信確認用の本文です。識別値: ' . $token;
Mail::mailer('mailpit_test')->raw(
$body,
function ($message) use ($recipient, $subject): void {
$message
->from('sender@example.test')
->to($recipient)
->subject($subject);
}
);
$mail = $this->waitForMail($subject);
self::assertSame($subject, $mail['Subject']);
self::assertSame([$recipient], array_column($mail['To'], 'Address'));
self::assertStringContainsString($body, $mail['Text']);
}
private function waitForMail(string $subject, float $seconds = 5): array
{
$baseUrl = rtrim(
(string) env('MAILPIT_API_URL', 'http://127.0.0.1:8025'),
'/'
);
$deadline = hrtime(true) / 1e9 + $seconds;
while (($remaining = $deadline - hrtime(true) / 1e9) > 0) {
$result = Http::acceptJson()
->connectTimeout(min(1, $remaining))
->timeout(min(2, $remaining))
->get($baseUrl . '/api/v1/search', [
'query' => 'subject:"' . $subject . '"',
'limit' => 2,
])
->throw()
->json();
self::assertIsArray($result);
self::assertIsInt($result['messages_count'] ?? null);
self::assertIsArray($result['messages'] ?? null);
if ($result['messages_count'] > 0) {
self::assertSame(1, $result['messages_count'], '対象メールが複数あります。');
$id = $result['messages'][0]['ID'] ?? null;
self::assertIsString($id);
$mail = Http::acceptJson()
->connectTimeout(1)
->timeout(2)
->get($baseUrl . '/api/v1/message/' . rawurlencode($id))
->throw()
->json();
self::assertIsArray($mail);
return $mail;
}
$remaining = $deadline - hrtime(true) / 1e9;
if ($remaining > 0) {
usleep((int) (min(0.1, $remaining) * 1_000_000));
}
}
self::fail('期限内に対象メールを受信できませんでした。件名: ' . $subject);
}
}
このコードのメールは架空の宛先への同期送信です。実際の業務メールを試す場合は、送信部分をアプリケーションのMailableや処理の呼び出しに置き換えます。その場合も、実在する宛先や個人情報を使わず、送信先が検証専用のMailpitであることを確認してください。
受信待ちとAPI通信失敗を分ける
メールがまだ見つからない場合だけ、100ミリ秒を目安に検索を繰り返します。検索の待ち時間は5秒が上限です。詳細取得には別途最大2秒を設定しているため、テスト全体が必ず5秒以内に終了するという意味ではありません。SMTP送信にも別のタイムアウトがあります。
throw()を付けているので、APIの4xx・5xxはHTTPエラーとして止まります。接続できない場合も例外になります。これらを握りつぶして「メール未着」と扱わないことで、SMTP側とAPI側の問題を分けて調べやすくなります。
検索結果の先頭や最新メールを無条件に使わない
毎回同じ件名を使うと、前回のメールを取得して成功扱いする可能性があります。今回は16バイトの乱数を16進文字列にして件名に付け、検索結果が1件であることを確認したうえで、件名・宛先・本文を照合しています。
本文は改行などの差を避けるため部分一致にしています。内容全体の一致が必要なら、改行コードなどの扱いを決めてから完全一致に変更してください。また、Toの確認はメールヘッダーの宛先の確認です。SMTPエンベロープの宛先やBccの検証まで含めた例ではありません。
テストを実行する
Mailpitを起動した状態で、Laravelプロジェクトのルートから実行します。
php artisan test --group=mailpit
Dockerなどで接続先が異なる場合は、MAILPIT_SMTP_HOST、MAILPIT_SMTP_PORT、MAILPIT_API_URLをテスト用環境へ設定します。SMTPの接続先とAPIの接続先が、同じMailpitを指していることも確認しましょう。
Mailpitを必要としない通常のテストでは、このグループを除外できます。
php artisan test --exclude-group=mailpit
確認した結果
掲載テストと補助検証で、次の動作を確認しました。
| 条件 | 結果 |
|---|---|
| 日本語本文のメールを同期送信 | 受信した件名・宛先・本文の照合に成功 |
| 別のメールがある状態で、未送信の件名を検索 | 他のメールを取得せず、期限で失敗 |
| 2プロセスから識別値の異なるメールを遅らせて送信 | それぞれの件名で異なるIDのメールを取得 |
| 同じ件名のメールを2通送信 | 重複として失敗 |
| 受信した本文に、存在しない文字列を期待 | 本文の照合で失敗 |
| APIの接続先を待受のないポートへ変更 | 未着ではなく接続例外になる |
未着の検証では、待ち時間を0.4秒に短縮しています。HTTPエラーについては、補助検証でLaravelのHttp::fake()から503を返し、例外になることも確認しました。これはAPIクライアントのエラー処理の確認であり、Mailpit自体の障害を再現したものではありません。
実行確認はDocker内で行っています。Windowsネイティブでの起動コマンドと、php artisan test経由の実行は未確認です。
失敗したときの確認先
| 止まった箇所 | 確認すること |
|---|---|
| SMTP送信で接続エラー | Mailpitの起動、SMTPのホスト・ポート |
| APIの接続・HTTPエラー | APIのURL、認証設定、HTTPステータス |
| 期限内にメールが見つからない | SMTPとAPIが同じ受信箱か、送信処理がFakeに置き換わっていないか |
| 宛先・件名・本文が不一致 | 実際に取得した項目と期待値、送信するメールの生成処理 |
取得した本文やヘッダーをそのままCIログへ出すと、メール内の情報も記録されます。必要な項目だけを確認し、テストにはダミーデータを使ってください。
運用するときの注意点
この例では受信箱を空にする処理を入れていません。並列実行中に全メールを削除すると、別のテストが待っているメールまで消してしまうためです。実行ごとの専用Mailpitを使うか、自分が取得したIDだけを対象に後片付けする方法を検討します。なお、詳細APIのGETは、そのメールを既読にする動作もあります。
キュー送信を確認したい場合は、別途キューワーカーが必要です。受信待ち時間にはキューの処理時間も影響するので、同期送信の例とは分けて検証してください。起動構成については、composer devでMailpitとキューワーカーをまとめて起動する記事も参考になります。
Mailpit側でBasic認証を有効にしている場合は、APIにも認証が必要です。今回のコードは認証なしのローカル環境用であり、認証付きAPI、キュー送信、HTMLメールの表示、添付ファイルは検証対象に含めていません。本番のメール配送先への到達や、迷惑メール判定を確認するテストでもありません。
通常のテストはメールFakeやMailableの検証を使い、SMTPを通した確認が必要な部分だけMailpitとの結合テストにすれば、テスト時間と確認範囲を調整しやすいかと思います。
参考資料
奈良市を拠点に、27年以上の経験を持つフリーランスWebエンジニア、阿部辰也です。
これまで、ECサイトのバックエンド開発や業務効率化システム、公共施設の予約システムなど、多彩なプロジェクトを手がけ、企業様や制作会社様のパートナーとして信頼を築いてまいりました。
【制作会社・企業様向けサポート】
Webシステムの開発やサイト改善でお困りの際は、どうぞお気軽にご相談ください。小さな疑問から大規模プロジェクトまで、最適なご提案を心を込めてさせていただきます。
ぜひ、プロフィールやWeb制作会社様向け業務案内、一般企業様向け業務案内もご覧くださいね。
Windows 11のLaravel 13でcomposer devにMailpitを追加し、キュー化したメールを確認する
2026.08.22
Windows 11のLaravel 13開発環境で、composer.jsonのdevスクリプトにMailpit、Laravel開発サーバー、キューワーカー、Viteを登録し、composer devからまとめて起動する方法を紹介します。データベースキューへ登録したテキストメールをMailpitで確認する流れに加え、php artisan devとの違い、MailpitのSMTP・Web UI設定、SQLiteファイルをGit管理から除外する方法、起動時の切り分けも説明します。
Windows 11にMailpitを導入してLaravelのメール送信を確認する
2026.08.06
Windows 11にMailpitを導入し、Laravel 13からSMTPでテストメールを送信して、MailpitのWeb UIで受信内容を確認する手順を紹介します。設定キャッシュ、ポート競合、キュー送信、メールFakeとの使い分けについても説明します。
Laravelのコードレビューで遅いSQLの候補を洗い出す
2026.10.02
Laravelのコードレビューで、ループ内のDBアクセスやEloquentのN+1、大量取得、検索条件とインデックスなど、性能問題につながりやすい箇所を候補として洗い出します。Laravelで発行SQLと実行時間を確認し、MySQLのEXPLAINや実データに近い環境での計測へつなげる方法を紹介します。コードレビューだけではSQLの実行時間を断定できない点も説明します。
Windows 11でDocker Composeを使ってLaravel環境を作る:Container・Volume・Networkの基本
2026.10.01
Windows 11のDocker Desktop上に、DockerfileとDocker Composeを使ってLaravel・PHP・MySQL・Mailpitの開発環境を構築します。ImageとContainerの関係、Bind MountとNamed Volumeによるデータの保存、ポート公開とContainer間通信の違いを実例で確認。LaravelからMySQLへ接続するときに、localhostではなくService名を使う理由も説明します。