ローカルメール検証ツール「Mailpit」をDockerで構築する手順

Linux

アプリ開発やEximなどのメールサーバー設定を検証するとき、「テストのつもりが本番のメールアドレスへ誤送信してしまった」「社内ネットワークから外部SMTPへのテスト送信がブロックされる」といったトラブルは避けたいところです。

そこで役立つのが、Dockerコマンド一発で起動できるローカル専用の検証メールサーバー&受信トレイ「Mailpit(メイルピット)」です。

この記事では、WSL2(AlmaLinux 9)+Docker環境で実際にaxllent/mailpit(v1.34.0)を構築・検証し、日本語HTMLメールのプレビュー、SMTP認証(AUTH)エラーの回避、MIMEヘッダ確認やREST API連携までをわかりやすく手順化しました。

この記事でわかること

  • MailHogの後継として人気が高いMailpitの特徴と実測リソース(メモリ約13.6MiB)
  • Docker Composeで「認証テストもそのまま通る」Mailpit環境を構築する手順
  • 日本語HTMLメール表示・MIMEヘッダ検証・REST API(/api/v1/messages)での自動テスト活用
  • 実機検証でつまずきやすいSMTP AUTHエラーや再起動時のデータ消失対策

Mailpitとは?MailHog後継として選ばれる理由と実機スペック

Mailpitは、ローカル開発環境やステージング環境から送信されたメールをすべて受け止め、外部へ一切配信せずにWebブラウザ上の受信トレイで中身を検証できるダミーSMTPサーバーです。

定番だったMailHogの開発停滞を受けて近年標準的に使われており、今回WSL2(AlmaLinux 9)上のDockerで実機確認したところ、以下のような軽快な動作スペックでした。

  • 検証バージョン:v1.34.0(Go 1.27.4製シングルバイナリ / イメージサイズ約50.8MiB[53,284,758 bytes])
  • アイドル時メモリ:docker stats 実測 13.57MiB(CPU 0.00%) と超軽量
  • 主要ポート:SMTP 1025/tcp、Web UI&API 8025/tcp、POP3 1110/tcp
  • 便利な標準機能:HTMLレスポンシブ切替(PC/タブレット/スマホ)、メールクライアント別CSS対応度スコア(HTML Check)、リンクチェック、REST API、ダークテーマ対応

Web UIの言語仕様について
Settings > Web UI を実機確認したところ、Mailpitの管理画面メニューは英語UIのみ(日本語切り替え設定はなし/タイムゾーン Asia/Tokyo (GMT+09:00) 設定は可能)です。ただし操作は「受信トレイ」「HTML・Headers・Rawタブ切替」程度の直感的な作りで、日本語の件名・本文・MIMEヘッダ・添付ファイル名は文字化けなく正確に表示できます。

Step 1:Docker ComposeでMailpitを起動する

任意の作業ディレクトリを作成し、docker-compose.yml を用意します。開発アプリ側からユーザー名・パスワード付きでSMTP送信するケースもそのまま受け取れるよう、最初から認証許可用の環境変数(MP_SMTP_AUTH_ACCEPT_ANY 等)を含めておくのが実務でのポイントです。

mkdir -p ~/mailpit && cd ~/mailpit
cat <<'EOF' > docker-compose.yml
services:
  mailpit:
    image: axllent/mailpit:latest
    container_name: mailpit
    restart: unless-stopped
    ports:
      - "8025:8025"   # Web UI・REST API
      - "1025:1025"   # SMTP受信ポート
    environment:
      TZ: Asia/Tokyo
      MP_MAX_MESSAGES: 5000
      MP_SMTP_AUTH_ACCEPT_ANY: 1
      MP_SMTP_AUTH_ALLOW_INSECURE: 1
EOF

設定ファイルを保存したら、以下のコマンドでコンテナを起動します。

docker compose up -d

起動後、ブラウザで http://localhost:8025 へアクセスすると、下の画像のようにMailpitのWeb受信トレイが表示されます(テストメール送信後の画面例)。

MailpitのWeb受信トレイ一覧画面(日本語件名・添付ファイルアイコン表示)
Web UI(http://localhost:8025)の受信トレイ画面。日本語の件名やプレビュー抜粋、添付ファイルアイコンが崩れず表示される

Step 2:ローカルSMTP(1025番)から日本語メールをテスト送信する

アプリ側の送信先設定を以下のように向けるだけで、本番環境へ誤送信するリスクをゼロにできます。

  • SMTPホスト:localhost(別コンテナから同一Dockerネットワーク経由で送る場合はサービス名 mailpit)
  • SMTPポート:1025
  • 暗号化 / TLS:不要(平文SMTP接続可)
  • SMTP認証(ID/パスワード):任意のダミー文字列(例:dev@example.local / dummy1234)で通過

動作確認として、WSL2・Linux端末からPython標準ライブラリ(smtplib)のみでHTMLメールを送信するテストコマンドを実行してみましょう。

python3 - <<'PYEOF'
import smtplib
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText

msg = MIMEMultipart("alternative")
msg["From"] = "no-reply@neta-verse.local"
msg["To"] = "admin@example.local"
msg["Subject"] = "【検証】パスワードリセットとログイン通知のご案内"
msg["X-App-Env"] = "local-staging"

plain = "ローカル環境からのパスワードリセット確認用テストメールです。"
html = "<html><body><h2>セキュリティ通知</h2><p>HTMLメールテスト:確認コード 849201</p></body></html>"
msg.attach(MIMEText(plain, "plain", "utf-8"))
msg.attach(MIMEText(html, "html", "utf-8"))

with smtplib.SMTP("127.0.0.1", 1025, timeout=10) as s:
    s.login("dev@example.local", "dummy1234")
    s.send_message(msg)
PYEOF

受信したメールをクリックすると、テーブル・ボタン装飾を含むHTMLレイアウトをそのままプレビューできます。タブ右側のスマホ/タブレット/PCアイコンで画面幅の切り替えができ、HTML Check や Link Check もワンクリックで確認できて非常に便利です。

Mailpitでの日本語HTMLメールプレビュー画面とHTML Check・Link Checkタブ
HTMLタブのプレビュー表示。上部の認証ユーザー名(Username)や HTML Check 84%・レスポンシブ切替ボタンまで一目で確認できる

Step 3:Exim件名デバッグにも効くヘッダ検証&REST API活用

Mailpitが技術検証で真価を発揮するのが、「メールアプリ上では日本語に見えるが、実際のプロトコル上どう送られているか」を素早く調べられる点です。

たとえば「日本語件名のメールフィルタ(EximやPostfix等)がうまく動かない」という調査では、Headers タブを開くことで「上部バーのデコード済み件名(【重要】サーバー監視アラート:Exim件名フィルタ検証テスト)」と「実際のヘッダ上のMIME Base64エンコード文字列(=?utf-8?b?...?=)」を一画面で見比べることができます。アプリ側が付与したカスタムヘッダ(X-Mail-Filter-Test 等)の検証にもそのまま使えます。

MailpitのHeadersタブ表示(MIMEエンコードされたSubjectとカスタムヘッダの検証画面)
Headersタブではエンコード済みの Subject 生文字列や Content-Transfer-Encoding・任意の X- カスタムヘッダを検索・確認できる

Exim側の日本語件名マッチの落とし穴については、別記事の Eximでメールの件名条件が機能しない原因と対策(MIMEエンコード問題) でも詳しく解説していますので、あわせてご覧ください。

REST APIで自動テスト(CI・スクリプト)からメールを検証する

ブラウザで目視するだけでなく、E2Eテストやシェルスクリプトから「メールが正しく届いたか」を自動アサーションしたい場合は、標準のREST API(http://localhost:8025/api/v1/)が便利です。

# 稼働情報と保存先・受信通数の確認
curl -s http://localhost:8025/api/v1/info

# 受信メール一覧のJSON取得
curl -s http://localhost:8025/api/v1/messages

実機で /api/v1/info を叩いた結果でも、以下のようにバージョン・DBパス・受信件数(Messages)がクリーンなJSONで即座に返却されます。

{"Version":"v1.34.0","LatestVersion":"v1.34.0","Database":"/tmp/mailpit-1795222127762898174.db","DatabaseSize":94208,"Messages":3,"Unread":3,...}

実機検証でハマりやすいポイントと対策

SMTP認証(login)が「SMTPNotSupportedError」で弾かれる

MP_SMTP_AUTH_ACCEPT_ANY=1 と MP_SMTP_AUTH_ALLOW_INSECURE=1 を指定せずに素の状態でMailpitを起動し、アプリやPython等からユーザー名・パスワード付き(server.login(...))で送信しようとすると、実機検証では以下のエラーで拒否されました。

SMTPNotSupportedError: ('SMTP AUTH extension not supported by server.',)

MailpitはデフォルトでSMTP AUTHおよび平文パスワード認証を受け付けない安全な設計になっているため、開発テスト用途で認証付きアプリから送る場合は前述の2つの環境変数をセットで有効化してください。

コンテナ再起動やWSL2再始動で受信トレイが空になる

上記の /api/v1/info 出力にある通り、Mailpitはデータ保存先を指定しない場合、コンテナ内の一時DB(/tmp/mailpit-*.db)へ書き込む仕様です。実際に今回の検証でも、WSL2の自動サスペンドからのコンテナ再起動時にテストメールがすべてリセット(0件)になりました。

検証ログをコンテナ再作成後も残したい場合は、ホスト側ディレクトリをマウントし MP_DATABASE を指定します。

    volumes:
      - ./data:/data
    environment:
      MP_DATABASE: /data/mailpit.db

ポート競合(8025 / 1025)と公開範囲の注意

ローカルで別の管理UI等がすでに 8025 番ポートを使用している場合は、ports: の左側のみ(例:"18025:8025")を変更して回避できます。また、Mailpitは任意のログイン認証を素通りさせる開発用ダミーサーバーのため、外部公開サーバー上で認証設定なしに 1025 / 8025 を開放しないよう注意してください。

関連ツール・おすすめ学習リソース

同じようにローカルDockerで安全・手軽に使える検証用ツールや、Exim設定・Docker基礎を固めたい方向けの関連記事・参考書もまとめています。

Dockerのボリューム永続化やコンテナ間ネットワーク、ポート設計を基礎から整理しておくと検証環境の構築がぐっと楽になります。

仕組みと使い方がわかる Docker&Kubernetesのきほんのきほん | 小笠原種高 |本 | 通販 | Amazon
Amazonで小笠原種高の仕組みと使い方がわかる Docker&Kubernetesのきほんのきほん。アマゾンならポイント還元本が多数。小笠原種高作品ほか、お急ぎ便対象商品は当日お届けも可能。また仕組みと使い方がわかる Docker&Kub...

メールのRawヘッダやアプリコード・ログ画面を並べて確認する作業には、文字がくっきり読める4Kモニターがあると快適です。

Amazon.co.jp: Dell S2722QC 27インチ 4K モニター (3年間無輝点交換保証/IPS非光沢/USB Type-C・HDMIx2/sRGB 99%/縦横回転・高さ調整/4ms/AMD FreeSync/スピーカー付) : パソコン・周辺機器
Amazon.co.jp: Dell S2722QC 27インチ 4K モニター (3年間無輝点交換保証/IPS非光沢/USB Type-C・HDMIx2/sRGB 99%/縦横回転・高さ調整/4ms/AMD FreeSync/スピーカー付...

まとめ

今回はDocker上で軽量・高速に動くダミーSMTP&Web受信トレイ「Mailpit」の構築手順と、実機検証で押さえておくべきポイントを解説しました。

今回のポイントおさらい

  • axllent/mailpit:latest はアイドル約13.6MiBと超軽量で、docker compose up -d ですぐ使える
  • MP_SMTP_AUTH_ACCEPT_ANY=1 と MP_SMTP_AUTH_ALLOW_INSECURE=1 を入れておくと認証付きアプリからのテスト送信もエラーなく通る
  • Headers タブで日本語件名のMIMEエンコードやカスタムヘッダを一目で検証でき、/api/v1/messages で自動テストも組める
  • 再起動後もメール履歴を残したい場合は MP_DATABASE とボリュームマウントを設定する

コメント

タイトルとURLをコピーしました