Mailpit 功能介绍与基本使用

发表于 分类于 ， Valine：

Mailpit 是一款轻量级、跨平台的本地 SMTP 服务器和邮件测试工具，用 Go 编写，单二进制部署，专为开发和测试场景设计。它能拦截应用发送的邮件，提供 Web UI 实时预览邮件内容，避免误发到真实邮箱。

一、核心功能

  • SMTP 服务器：监听 1025 端口，接收任意应用发出的邮件，无需真实账号密码
  • Web UI 邮件预览：监听 8025 端口，浏览器实时查看收件箱、HTML / 纯文本 / 源码视图
  • HTML 兼容性检测：自动检查邮件 HTML 在主流邮件客户端的渲染兼容性
  • 链接和拼写检查：内置链接可达性检测、拼写检查（spamassassin 集成可选）
  • REST API：提供完整的 API 用于自动化测试场景（搜索、删除、发信）
  • WebSocket 实时推送：UI 收到新邮件即时刷新，无需手动重载
  • 支持附件、多语言、Chaos 测试模式

二、安装与启动

2.1 启动脚本（Docker，已避开端口冲突 + 修复 WSL 路由）

#!/bin/bash
# mailpit - 本地邮件调试工具
# UI:   http://localhost:18025
# SMTP: localhost:11025

set -e

# 修复 WSL mirrored 模式下 docker0 路由被 VPN 覆盖的问题
sudo ip route add 172.17.0.0/24 dev docker0 src 172.17.0.1 2>/dev/null || true

# 停掉旧容器（如存在）
docker rm -f mailpit 2>/dev/null || true

docker run -d \
  --name mailpit \
  --restart unless-stopped \
  --network host \
  -e MP_UI_BIND_ADDR=0.0.0.0:18025 \
  -e MP_SMTP_BIND_ADDR=0.0.0.0:11025 \
  -e MP_SMTP_AUTH_ACCEPT_ANY=1 \
  -e MP_SMTP_AUTH_ALLOW_INSECURE=1 \
  -v mailpit-data:/data \
  axllent/mailpit:latest

echo 'mailpit started'
echo '  UI:   http://localhost:18025'
echo '  SMTP: localhost:11025'

2.2 关键环境变量

变量 说明
MP_UI_BIND_ADDR Web UI 监听地址，默认 0.0.0.0:8025
MP_SMTP_BIND_ADDR SMTP 监听地址，默认 0.0.0.0:1025
MP_SMTP_AUTH_ACCEPT_ANY =1 时接受任意 SMTP 认证（开发用）
MP_SMTP_AUTH_ALLOW_INSECURE =1 时允许非 TLS 连接
MP_MAX_MESSAGES 邮件最大保留数，默认 500
MP_DATA_FILE 邮件存储数据库路径

三、基本使用

3.1 Web UI 访问

启动成功后浏览器访问 http://localhost:18025，可看到收件箱列表、搜索、HTML 预览、源码、附件等功能。

3.2 应用接入（业务代码侧）

把应用的 SMTP 配置改成 mailpit 的地址即可，无需账号密码：

spring:
  mail:
    host: localhost
    port: 11025
    username: any
    password: any
    properties:
      mail.smtp.auth: false
      mail.smtp.starttls.enable: false

3.3 命令行测试发信

curl -s --url 'smtp://127.0.0.1:11025' \
  --mail-from 'sender@test.com' \
  --mail-rcpt 'receiver@test.com' \
  --upload-file - <<'EOF'
From: sender@test.com
To: receiver@test.com
Subject: Hello Mailpit

This is a test email.
EOF

3.4 通过 REST API 发信

curl -X POST http://localhost:18025/api/v1/send \
  -H 'Content-Type: application/json' \
  -d '{
    "From": {"Email": "sender@test.com", "Name": "Sender"},
    "To": [{"Email": "receiver@test.com"}],
    "Subject": "Hello via API",
    "Text": "Plain text body",
    "HTML": "<h1>HTML body</h1>"
  }'

四、常用 REST API

方法 路径 说明
GET /api/v1/messages 获取邮件列表（支持分页）
GET /api/v1/message/{id} 获取单封邮件详情
GET /api/v1/search?query=... 搜索邮件
POST /api/v1/send 通过 API 发信
DELETE /api/v1/messages 清空所有邮件（或按 ID 删除）

五、避坑指南（基于 WSL 实际部署）

WSL mirrored 网络模式下的注意事项

  1. 默认 8025/1025 端口可能与 Windows 侧 portproxy 或其他服务冲突，建议改成 18025/11025
  2. 公司 VPN（FSE/OpenVPN）会下发 172.17.0.0/20 路由，覆盖 Docker 默认 docker0 路由，导致容器网络不通；启动脚本里加 ip route add 172.17.0.0/24 dev docker0 修复
  3. 使用 --network=host 模式可绕开 docker-proxy 路由问题
  4. 每次 WSL 重启后路由会重置，建议把启动命令做成脚本，每次重启后执行一次

六、参考链接

  • 官方仓库：https://github.com/axllent/mailpit
  • 官方文档：https://mailpit.axllent.org/docs/
  • Docker 镜像：https://hub.docker.com/r/axllent/mailpit
相关文章