技術資料

Laravelでメール送信を確認するとき、開発中のメールを実在するメールアドレスへ送信する方法は避けたいものです。

Mailpitを使えば、Laravelから送信したメールをローカルで受け取り、Web UIで内容を確認できます。ただし、メール送信をキューへ登録する構成では、Mailpitだけでなくキューワーカーも起動しておく必要があります。

今回は、Laravelプロジェクトのcomposer.jsonを変更し、composer devで次の4プロセスをまとめて起動する構成を作ります。

• Mailpit
• Laravel開発サーバー
• キューワーカー
• Vite開発サーバー

そのうえで、キューへ登録したテキストメールをMailpitで確認します。

前提

今回の対象環境は以下の通りです。

• OS: Windows 11
• ターミナル: PowerShell
• Laravel Framework: 13.x
• PHP、Composer、Node.js、npm
• Mailpit: C:\Tools\Mailpitへ配置済み

Mailpitの実行ファイルへPATHを設定済みで、PowerShellから次のコマンドを実行できる状態を前提にします。

mailpit version

Laravelプロジェクトは作成済みで、プロジェクトのルートディレクトリから以降のコマンドを実行します。

Mailpitの導入そのものについては、以前のWindows 11でMailpitを導入してLaravelのメール送信を確認する記事で説明しています。今回はMailpitが利用できる状態から始めます。

今回の構成

composer devを実行すると、Composerのdevスクリプトからconcurrentlyを起動します。concurrentlyが、Mailpit、Laravel開発サーバー、キューワーカー、Viteを個別のプロセスとして起動します。

composer dev
    |
    v
concurrently
    ├─ mailpit
    ├─ php artisan serve
    ├─ php artisan queue:listen --tries=1 --timeout=0
    └─ npm run dev

Laravelからメールを送信すると、次のように処理されます。

LaravelのJob
    |
    v
データベースキュー
    |
    v
キューワーカー
    |
    v
MailpitのSMTPサーバー（127.0.0.1:1025）
    |
    v
Mailpit Web UI（http://127.0.0.1:8025/）

キューへ登録しただけではメールは送信されません。キューワーカーがJobを取り出して処理することで、LaravelからMailpitへSMTP接続が行われます。

Mailpitの接続先を確認する

Mailpitは、Web UIとSMTPサーバーをそれぞれ次の接続先で起動します。

• Web UI: http://127.0.0.1:8025/
• SMTP: 127.0.0.1:1025
• データベース: storage/mailpit.db

Mailpitの既定値は、Web UIが8025番ポート、SMTPが1025番ポートです。今回の設定では待受アドレスを127.0.0.1に限定します。

Mailpitの既定の待受アドレスは0.0.0.0です。また、既定のSMTPは暗号化と認証を使用しません。ローカル開発だけで使う場合でも、外部ネットワークへ公開しないように待受アドレスを明示します。詳しくはMailpitのランタイムオプションとSMTPサーバーの設定を参照してください。

Mailpitの起動コマンド

今回のMailpitの起動コマンドは次の通りです。

mailpit --listen 127.0.0.1:8025 --smtp 127.0.0.1:1025 --database storage/mailpit.db

--listenはWeb UIの待受アドレス、--smtpはSMTPサーバーの待受アドレスです。--databaseには、受信メールを保存するSQLiteファイルを指定しています。

--databaseを指定しない場合、Mailpitは一時データベースを使用します。Mailpitを終了するとデータも削除されるため、確認したメールを再起動後も残したい場合は、今回のように保存先を指定します。MailpitのSQLite保存ではWALが使われるため、次のような関連ファイルも作成されます。

storage/mailpit.db
storage/mailpit.db-shm
storage/mailpit.db-wal

.gitignoreへ追加する

MailpitのSQLiteデータベースにはメール本文やヘッダーが保存されます。テストメールの内容をGitへ登録しないように、プロジェクトの.gitignoreへ次の行を追加します。

/storage/mailpit.*

Mailpitの保存方法については、Mailpitのメール保存に関するドキュメントも確認してください。

Laravelのメールとキューを設定する

メール設定を変更する

Laravelプロジェクトの.envへ、MailpitのSMTP接続先を設定します。

MAIL_MAILER=smtp
MAIL_SCHEME=null
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null

MAIL_FROM_ADDRESS="noreply@example.test"
MAIL_FROM_NAME="${APP_NAME}"

Mailpitの既定SMTPは暗号化と認証を使用しないため、ユーザー名とパスワードは設定していません。Mailpit側でTLSや認証を有効にした場合は、Laravel側の設定も合わせて変更します。

古いLaravelプロジェクトでは、MAIL_SCHEMEではなくMAIL_ENCRYPTIONを参照している場合があります。対象プロジェクトのconfig/mail.phpが、どの環境変数を参照しているか確認してください。

キュー接続を設定する

今回は、追加のキューサービスを使わずに確認できるよう、データベースキューを使用します。.envに次の設定を追加または変更します。

QUEUE_CONNECTION=database

データベースキューでは、Jobを保存するjobsテーブルが必要です。プロジェクトにキュー用のMigrationが存在しない場合だけ、次のコマンドを実行します。

php artisan make:queue-table
php artisan migrate

すでに同じMigrationがある場合は、重複して作成しないでください。database/migrationsを確認してから、必要なMigrationだけを実行します。

設定キャッシュを削除する

.envの変更が反映されない場合は、Laravelの設定キャッシュを削除します。

php artisan config:clear

現在読み込まれている設定値は、Tinkerで確認できます。

php artisan tinker

config('mail.default');
config('mail.mailers.smtp.host');
config('mail.mailers.smtp.port');
config('queue.default');

今回の設定では、主に次の値になっていれば問題ありません。

default mailer: smtp
SMTP host: 127.0.0.1
SMTP port: 1025
default queue: database

Tinkerはexitを入力して終了します。

composer.jsonを変更する

Laravel 13の標準プロジェクトには、開発用のdevスクリプトが用意されています。現在のLaravelでは、標準のdev構成から、PHP開発サーバー、キューワーカー、ログ表示、Viteを起動できます。

今回はログ表示のプロセスをMailpitへ置き換え、Mailpit、Laravel開発サーバー、キューワーカー、Viteを起動する構成にします。composer.jsonのscripts.devを次のように変更します。

"dev": [
    "Composer\\Config::disableProcessTimeout",
    "npx concurrently -c \"#93c5fd,#c4b5fd,#fb7185,#fdba74\" \"mailpit --listen 127.0.0.1:8025 --smtp 127.0.0.1:1025 --database storage/mailpit.db\" \"php artisan serve\" \"php artisan queue:listen --tries=1 --timeout=0\" \"npm run dev\" --names=mailpit,server,queue,vite --kill-others"
]

JSONの文字列内では、PHPの名前空間を表すバックスラッシュを\\と記述します。既存のdevスクリプトを置き換える場合は、カンマやダブルクォートの対応が崩れていないか確認してください。

各プロセスの役割

• mailpit: SMTPサーバーとWeb UIを起動する。
• php artisan serve: Laravelの開発サーバーを起動する。
• php artisan queue:listen --tries=1 --timeout=0: キューを監視してJobを処理する。
• npm run dev: Viteの開発サーバーを起動する。

Composer\\Config::disableProcessTimeoutは、Composerから起動した開発用プロセスが長時間実行されても、Composerのスクリプトタイムアウトで終了しないようにする設定です。開発用の常駐プロセスをまとめて起動するために、Laravelの標準スクリプトでも使われています。

--names=mailpit,server,queue,viteは、ターミナルに表示するプロセス名を指定します。--kill-othersは、いずれかのプロセスが終了したときに、他のプロセスも終了させるオプションです。

プロジェクトに必要なNode.jsパッケージがまだインストールされていない場合は、先に次のコマンドを実行します。

npm install

composer devを実行する

プロジェクトのルートディレクトリで、次のコマンドを実行します。

composer dev

正常に起動すると、プロセス名を付けたログが表示されます。表示内容は環境やパッケージのバージョンによって異なりますが、次のような名前を確認できます。

[mailpit] Mailpit SMTP / HTTP server
[server]  Laravel development server
[queue]   Laravel queue listener
[vite]    Vite development server

MailpitのWeb UIをブラウザで開きます。

http://127.0.0.1:8025/

Laravelの開発サーバーは、通常は次のURLで開きます。

http://127.0.0.1:8000/

終了するときは、起動中のターミナルでCtrl + Cを押します。Windowsでプロセス終了の確認が表示された場合は、内容を確認してからYを入力します。

キューへテストメールを登録する

次に、キューへ登録されたJobからテキストメールを送信します。今回は、MailableではなくJobのhandleメソッドでMail::raw()を呼び出すシンプルな例にします。

Jobを作成する

プロジェクトのルートディレクトリで、Jobを作成します。

php artisan make:job SendTestMail

app/Jobs/SendTestMail.phpを次の内容に変更します。

<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Mail;

class SendTestMail implements ShouldQueue
{
    use Queueable;

    public function handle(): void
    {
        Mail::raw(
            'キュー経由のテストメールです。',
            function ($message): void {
                $message
                    ->to('test@example.com')
                    ->subject('キュー経由のテストメール');
            }
        );
    }
}

ShouldQueueを実装したJobは、dispatch()で呼び出すとキューへ登録されます。handle()の処理は、キューワーカーがJobを取り出したときに実行されます。

Jobをキューへ登録する

別のPowerShellでTinkerを起動し、Jobをキューへ登録します。

php artisan tinker

App\Jobs\SendTestMail::dispatch();

データベースキューを使用している場合、dispatch()直後にメールが送信されるとは限りません。まずjobsテーブルへJobが登録され、起動中のキューワーカーがJobを取り出して処理します。

Tinkerはexitで終了します。composer devを実行しているターミナルの[queue]ログに処理結果が表示され、Mailpitの受信箱にメールが追加されることを確認します。

Mailpitでメールを確認する

ブラウザでMailpitのWeb UIを開きます。

http://127.0.0.1:8025/

受信箱に「キュー経由のテストメール」という件名のメールが表示されれば、次の処理がつながっています。

1. LaravelがJobをキューへ登録した。
2. キューワーカーがJobを取り出した。
3. JobがLaravelのメール送信処理を呼び出した。
4. LaravelがMailpitのSMTPサーバーへ接続した。
5. Mailpitがメールを保存し、Web UIへ表示した。

今回はシンプルなテキストメールを送信しています。HTMLメールや添付ファイルを確認したい場合は、実際にアプリケーションで使用するMailableへ置き換えて、Mailpitの画面で確認します。

composer devとphp artisan devの違い

composer devは、プロジェクトのcomposer.jsonにあるscripts.devをComposerから実行するコマンドです。Composerでは、スクリプト名を直接指定する方法のほか、composer run-script devやcomposer run devのように明示して実行する方法があります。

一方、php artisan devはLaravel 13が提供するArtisanコマンドです。標準では、PHP開発サーバー、キューワーカー、ログ表示、Viteをまとめて起動します。現在のLaravel公式ドキュメントでは、Windowsではプロセス管理にconcurrentlyが使われ、Node.js 22.13以上が必要と説明されています。

今回のcomposer devは、Laravelの標準構成をそのまま呼び出しているわけではありません。composer.jsonでプロセス一覧を定義し、標準のログ表示プロセスをMailpitへ置き換えた、プロジェクト固有の構成です。

Laravel 13の標準的なphp artisan devのプロセスを確認したい場合は、次のコマンドを実行します。

php artisan dev:list

Mailpitを含めた起動構成を使う場合は、今回のようにComposerスクリプトへ明示的に追加する方法のほか、LaravelのDevCommandsを使ってArtisan側の開発プロセスへ登録する方法もあります。まずは既存プロジェクトのcomposer.jsonとphp artisan dev:listの結果を確認して、どこへ追加するか判断するとよいかと思います。

うまく動かない場合

mailpitコマンドが見つからない

PowerShellで次のコマンドを実行し、Mailpitの実行ファイルが見つかるか確認します。

Get-Command mailpit

C:\Tools\Mailpit\mailpit.exeが表示されない場合は、システム環境変数のPATHにC:\Tools\Mailpitが含まれているか確認します。環境変数を変更した後は、変更前から開いていたPowerShellではなく、新しいPowerShellを起動してください。

MailpitのWeb UIやSMTPへ接続できない

まず、Mailpitのプロセスが起動しているか確認します。Web UIとSMTPのポートへ接続できるかは、次のコマンドで確認できます。

Test-NetConnection 127.0.0.1 -Port 8025
Test-NetConnection 127.0.0.1 -Port 1025

TcpTestSucceeded : Falseの場合は、Mailpitの起動ログ、--listenと--smtpの指定、別のアプリケーションによるポート使用を確認します。

ポートを変更する場合は、Mailpitの起動引数とLaravelのMAIL_PORTを同じ値に変更します。Web UIのポートを変更した場合は、ブラウザで開くURLも変更してください。

メールがMailpitに表示されない

まず、Laravelのメール設定がMailpitを指定できているか確認します。

php artisan tinker

config('mail.default');
config('mail.mailers.smtp.host');
config('mail.mailers.smtp.port');
config('queue.default');

次に、QUEUE_CONNECTIONがdatabaseになっているか、jobsテーブルが存在するか、[queue]プロセスが起動しているか確認します。

SMTP接続の問題とキュー処理の問題を分けたい場合は、いったんキューを使わず、TinkerからMail::raw()を実行します。それでMailpitに表示されるなら、SMTP設定ではなく、Jobの登録やキューワーカーの起動を確認します。

Viteだけ起動しない

Node.jsとnpmが利用できるか確認し、プロジェクトのルートで次のコマンドを個別に実行します。

node --version
npm --version
npm install
npm run dev

composer devでは複数のプロセスを同時に起動するため、原因を切り分けるときはMailpit、Laravel開発サーバー、キューワーカー、Viteを一つずつ起動します。

一つのプロセスが終了すると全て終了する

今回の設定では--kill-othersを指定しているため、一つのプロセスが終了すると、他のプロセスも終了します。これは開発環境をまとめて停止できる一方、原因調査中はログを確認しにくい場合があります。

原因を調べるときは、composer.jsonのコマンドを一時的に個別実行し、どのプロセスが終了しているのか確認します。原因を確認した後は、4プロセスをまとめて起動する設定へ戻します。

注意点

• Mailpitは開発・テスト用のツールであり、本番環境のメール配送サービスとして使用しない。
• MailpitのSMTPは既定で暗号化・認証なしのため、127.0.0.1などローカルの待受アドレスに限定する。
• MailpitのSQLiteデータベースにはメール本文や個人情報が保存される可能性があるため、実在する個人情報をテストに使用しない。
• storage/mailpit.*をGit管理へ含めない。
• php artisan queue:listen --tries=1 --timeout=0は開発用の設定であり、本番環境のキューワーカーへそのまま使用しない。
• キューへ登録したメールがデータベースのトランザクションに依存する場合は、コミット前にJobが処理されないよう、Laravelのキューとトランザクションに関する仕様を確認する。

まとめ

今回は、Laravelプロジェクトのcomposer.jsonへMailpitの起動コマンドを追加し、composer devからMailpit、Laravel開発サーバー、キューワーカー、Viteをまとめて起動する構成を紹介しました。

キュー化したメールは、Jobをキューへ登録するだけでは送信されません。キューワーカーがJobを処理し、LaravelがMailpitのSMTPサーバーへ接続することで、MailpitのWeb UIからメールを確認できます。

composer devはプロジェクトのComposerスクリプト、php artisan devはLaravelのArtisanコマンドです。どちらも開発用プロセスをまとめて起動できますが、Mailpitを含めるかどうかはプロジェクトの設定によって変わります。まずは既存のcomposer.jsonとLaravelの開発用プロセスを確認し、必要なプロセスだけを追加するとよいかと思います。

参考資料

• Laravel 13.x Artisan Console
• Laravel 13.x Mail
• Laravel 13.x Queues
• Laravel 13.x Configuration
• Composer Scripts
• Mailpit Runtime options
• Mailpit Email storage
• concurrently