sj26/mailcatcher

MailCatcher

镜像概述和主要用途

MailCatcher是一个轻量级工具，运行简单的SMTP服务器以捕获所有发送至其的邮件，并通过Web界面直观展示。它适用于开发和测试环境，帮助开发者在不发送真实邮件的情况下，查看应用程序发送的邮件内容、格式及附件，简化邮件功能调试流程。

核心功能和特性

• 邮件捕获与存储：捕获所有发送至SMTP服务器的邮件并存储，供后续查看
• 多格式支持：展示邮件的HTML、纯文本及原始源代码版本（如适用）
• HTML优化：重写HTML内容，支持嵌入式图片显示，链接在新窗口打开
• 附件管理：列出邮件附件，支持单独下载各部分内容
• 原生客户端查看：可下载原始邮件，在本地邮件客户端中查看
• 灵活配置：通过命令行选项自定义SMTP/HTTP的IP和端口设置
• 实时更新：支持WebSocket的浏览器可实时显示新邮件，否则每30秒更新一次
• 运行模式：支持后台守护进程或前台运行模式
• 命令行工具：提供catchmail命令，简化PHP等应用的邮件发送配置
• 键盘导航：支持键盘快捷键在邮件间导航

使用场景和适用范围

• 开发环境邮件测试：在应用开发过程中，测试邮件发送功能而不发送真实邮件
• 邮件格式验证：检查HTML邮件格式、嵌入式图片、附件等是否正确
• 多框架集成：适用于Rails、PHP、Django等多种开发框架的邮件功能调试
• CI/CD流程：在持续集成过程中验证邮件发送逻辑

详细使用方法和配置说明

Docker运行命令

bash
# 基本运行（默认SMTP端口1025，HTTP端口1080）
docker run -d -p 1025:1025 -p 1080:1080 --name mailcatcher sj26/mailcatcher

# 自定义SMTP和HTTP端口
docker run -d -p 25:25 -p 8080:8080 --name mailcatcher sj26/mailcatcher --smtp-port 25 --http-port 8080

# 绑定到特定IP（例如允许外部访问）
docker run -d -p 1025:1025 -p 1080:1080 --name mailcatcher sj26/mailcatcher --smtp-ip 0.0.0.0 --http-ip 0.0.0.0

命令行选项说明

框架配置示例

Rails

在config/environments/development.rb中添加：

ruby
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = { 
  address: '127.0.0.1',  # Docker主机IP或容器名称
  port: 1025 
}
config.action_mailer.raise_delivery_errors = false

PHP

修改php.ini或Apache配置：

ini
; php.ini配置
sendmail_path = /usr/bin/env catchmail -f from@example.com

; Apache配置
php_admin_value sendmail_path "/usr/bin/env catchmail -f from@example.com"

若MailCatcher使用自定义端口：

ini
sendmail_path = /usr/bin/env catchmail --smtp-port 25 -f from@example.com

Django

在settings.py中添加：

python
if DEBUG:
    EMAIL_HOST = '127.0.0.1'  # Docker主机IP或容器名称
    EMAIL_HOST_USER = ''
    EMAIL_HOST_PASSWORD = ''
    EMAIL_PORT = 1025
    EMAIL_USE_TLS = False

API接口

MailCatcher提供RESTful API接口：

• /messages：获取邮件列表（JSON格式）
• /messages/:id.json：获取指定邮件的元数据
• /messages/:id.html：获取邮件HTML内容
• /messages/:id.plain：获取邮件纯文本内容
• /messages/:id.source：获取邮件原始源代码
• /messages/:id/:cid：通过CID获取附件

注意事项

• 邮件处理：基础邮件处理功能可通过修改源码扩展，若遇到问题可提交issue并提供完整邮件内容
• 编码支持：对UTF-8编码支持有限，建议使用能根据SMTP服务器能力正确编码的邮件库
• 网络配置：默认仅本地访问，如需外部访问需通过--smtp-ip 0.0.0.0和--http-ip 0.0.0.0绑定到所有网络接口

许可证

MailCatcher基于MIT许可证开源，详情参见https://github.com/sj26/mailcatcher/blob/master/LICENSE%E3%80%82