MailSend

MailHub

MailHub 是一个 Docker 化的多用户邮件控制面板、SMTP Submission 服务和收发 API。它面向需要自托管邮件能力的团队，提供域名验证、DKIM 签名、DNS 配置提示、邮箱账号、SMTP 凭据和 API Token 管理。

功能

• 多用户账号体系，隔离域名、SMTP 凭据、DNS API 凭据、API Token 和发送记录。
• 为发信域名生成验证 TXT、DKIM、SPF、DMARC、发信主机 A 记录和 PTR 检查提示。
• 支持 Cloudflare、阿里云 DNS、腾讯云 DNSPod API 的基础 DNS 写入。
• 检查公网 DNS 中的 SPF、DKIM、DMARC、PTR 和发信主机 A 记录状态。
• 通过内部 Postfix 出站队列发送邮件，并按发件域名添加 DKIM 签名。
• 提供 SMTP Submission 和 HTTP 发送 API。
• 通过 Dovecot 提供完整 IMAP/POP3 客户端兼容，Maildir 作为邮件真源。
• 内置 React + Ant Design 管理界面。

技术栈

• Node.js ESM，要求 Node.js >=24.0.0
• SQLite 持久化
• React、Vite、Ant Design
• Docker Compose + Postfix + Dovecot
• Node 内置 node:test

快速开始

cp .env.example .env
npm install
npm test
npm run build
npm run prepare:dovecot
docker compose up -d --build
docker compose logs -f app postfix dovecot

默认管理面板通过 APP_PORT 暴露到宿主机 127.0.0.1:3025。生产环境建议使用 Nginx、Caddy 或其他反向代理提供 HTTPS。

首次启动前务必修改 .env 中的默认管理员密码、SESSION_SECRET、SMTP 凭据和域名/IP 配置。

配置

以 .env.example 为模板创建 .env。常用配置包括：

• APP_BASE_URL：管理面板和发送 API 的公网访问地址。
• MAIL_HOSTNAME：出站邮件 HELO、Postfix myhostname 和 DNS 指南中的发信主机名。
• SENDING_IP：发信服务器公网 IP。
• SESSION_SECRET：会话和服务端加密使用的随机密钥，生产环境必须使用强随机值。
• SUBMISSION_HOST、SUBMISSION_PORTS：SMTP Submission 对外连接信息。
• SUBMISSION_TLS_CERT、SUBMISSION_TLS_KEY：TLS 证书路径。证书文件应放在本地 certs/，不要提交到 Git。
• MAIL_ACCESS_BACKEND：Docker 部署使用 dovecot；仅本地协议回归时可使用 legacy。
• MAILDIR_ROOT、MAILDIR_SYNC_INTERVAL_MS：Maildir 持久化目录及管理界面索引同步周期；默认 300000 毫秒（5 分钟），可按邮件量调整。
• DEFAULT_SPF_MECHANISMS：需要保留的第三方 SPF include，例如事务邮件服务商。
• SEND_REQUIRES_VERIFIED：是否要求域名 DNS 验证通过后才能发信。
• LIST_UNSUBSCRIBE_MAILTO、LIST_UNSUBSCRIBE_URL：可选退订头配置，支持 {eventId}、{recipient}、{sender}、{domain}、{userId} 占位符。
• LIST_UNSUBSCRIBE_POST_ENABLED：是否添加 one-click 退订头；仅在退订 URL 真正支持合规 POST 时开启。
• FEEDBACK_ID_ENABLED：是否为 API 发信添加不含明文邮箱的 Feedback-Id。
• REPORT_ABUSE_TO、CSA_COMPLAINTS_TO：可选投诉处理邮箱头。
• BOUNCE_ADDRESS、BOUNCE_ENVELOPE_ENABLED：可选退信 envelope sender；确认 bounce 邮箱/域名可收信和处理前不要开启。

SMTP 发信

MailHub 提供公网 SMTP Submission。所有发信端口都需要 SMTP AUTH，未认证请求不会转发邮件，避免开放中继。

Host: 由 SUBMISSION_HOST 配置，例如 smtp.mailhub.example.com
Port 25:   SMTP + STARTTLS + AUTH
Port 587:  SMTP Submission + STARTTLS + AUTH
Port 465:  SMTPS implicit TLS + AUTH
Port 2525: SMTP + STARTTLS + AUTH
Username: 用户在网页“SMTP 凭据”中配置
Password: 用户在网页“SMTP 凭据”中配置

SMTP 密码会同时保存哈希和服务端加密密文：哈希用于认证，加密密文用于用户本人在网页复制。旧数据如果只有哈希，无法反解，需要用户重新设置一次密码后才能复制。

IMAP / POP3 收信

Docker Compose 中由 Dovecot 独占 IMAP/POP3 端口，MailHub Node 服务不再直接实现客户端协议。邮箱地址和原密码继续由 MailHub 认证，Vesta 导入的 MD5-CRYPT 密码首次登录成功后会自动升级为 scrypt，不需要用户改密码。Compose 默认固定开放 IMAP 与 POP3；旧的 IMAP_ENABLED、POP3_ENABLED、IMAP_PORTS、POP3_PORTS 只用于本地 legacy 协议回归。若生产环境不提供某个协议，应通过 IMAP_BIND / POP3_BIND、Compose override 或防火墙限制对应端口。

IMAP: 143 STARTTLS / 993 implicit TLS
POP3: 110 STLS / 995 implicit TLS
Username: 完整邮箱地址
Password: 邮箱原密码或在 MailHub 设置的新密码

邮件原始字节、文件夹、已读和 flags 以 data/maildir/ 为准；SQLite 保留管理界面/API 的检索索引。Dovecot 内的移动、已读、APPEND 和 EXPUNGE 会由后台同步到该索引。首次切换应短暂停止 app 与 Dovecot，再通过 app 镜像运行 node scripts/migrate-sqlite-maildir.js；迁移可重复执行，且会跳过已经切换到 Maildir 的邮件。

API Token 与收发 API

每个用户可以在面板生成自己的 API Token。新 Token 会以哈希用于认证，并以服务端加密密文供所属账号在面板完整查看和复制；升级前创建、仅保存哈希的历史 Token 无法反解，可在面板确认后重新生成。

Token 支持以下权限：

• send：发送邮件。
• mailboxes:read：查询可访问邮箱的元数据。
• mailboxes:write：创建长期或临时邮箱。
• messages:read：查询收到的邮件列表、文件夹和邮件正文。

收信读取还受 Token 邮箱范围约束：默认仅 Token 所有者名下邮箱，也可限定到指定邮箱；管理员可显式授予全系统邮箱读取权限。该范围同样约束带 mailboxes:read 权限的邮箱元数据列表。

curl -X POST https://mailhub.example.com/api/send \
  -H "Authorization: Bearer <USER_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@example.com",
    "to": "user@example.net",
    "subject": "Hello from MailHub",
    "text": "Signed with DKIM and queued by MailHub."
  }'

发送时会校验 From 所属域名必须归当前 Token 所属用户所有。.env 中的 API_TOKEN 仅作为旧版 admin 兼容发送 token，新用户应使用网页生成的用户级 Token。

查询收信列表和邮件详情：

curl -H "Authorization: Bearer <INBOUND_API_TOKEN>" \
  "https://mailhub.example.com/api/inbound-messages?page=1&pageSize=20&folder=INBOX&read=false"

curl -H "Authorization: Bearer <INBOUND_API_TOKEN>" \
  "https://mailhub.example.com/api/inbound-messages/123"

curl -H "Authorization: Bearer <INBOUND_API_TOKEN>" \
  "https://mailhub.example.com/api/inbound-mailboxes/42/folders"

列表接口支持 page、pageSize、mailboxId、folder、read 和 q；详情接口返回 rawMessage、textBody 与 htmlBody；文件夹接口返回标准用途、邮件数和未读数。未授权邮箱不会出现在列表中，直接读取详情或文件夹时返回 404。

DNS API 一键配置

用户可在网页“DNS API”中保存以下服务商凭据：

• Cloudflare：API Token，建议只授予目标 Zone 的 DNS Edit 权限；可选 Zone ID。
• 阿里云 DNS：AccessKeyId 和 AccessKeySecret。
• 腾讯云 DNSPod：SecretId 和 SecretKey。

域名绑定 DNS 凭据后，点击“一键配置 DNS”会写入或更新验证 TXT、DKIM TXT、SPF TXT、DMARC TXT 和发信主机 A 记录。PTR 反向解析只检测和提示，通常必须在云服务器或 IP 服务商控制台配置。

部署

生产环境建议：

1. 将仓库部署到服务器目录，例如 /opt/mailhub。
2. 基于 .env.example 创建 .env，填写真实域名、IP、证书路径和强随机密钥。
3. 将 TLS 证书放在本地 certs/ 目录，确保私钥不会进入 Git。如证书由宝塔等主机端工具续期，可在 .env 中设置 MAILHUB_CERT_SOURCE_DIR，该目录需包含 fullchain.pem 和 privkey.pem。
4. 以 root（或 Linux 宿主 UID 1000）运行 npm run prepare:dovecot，生成仅 app 与 Dovecot 可读的内部认证 secret；脚本会在不兼容的 Linux UID 下直接失败，避免启动后才发现 Maildir/secret 无权限。
5. 运行 docker compose build app postfix，然后用 docker compose stop app dovecot 开始短维护窗口。
6. 运行 docker compose run --rm --no-deps -T app node scripts/migrate-sqlite-maildir.js，把现有 SQLite 邮件可重入地写入 Maildir；迁移完成前不要让旧 IMAP 或 SMTP 入站继续写邮件。
7. 运行 docker compose up -d 恢复服务。
8. 使用反向代理把 HTTPS 流量转发到 127.0.0.1:${APP_PORT}。
9. 在云防火墙和系统防火墙中放行需要的 SMTP、IMAP 和 POP3 端口。

可选的远程部署脚本需要显式提供目标服务器和目录：

MAILHUB_DEPLOY_REMOTE=deploy@example.com \
MAILHUB_DEPLOY_DIR=/opt/mailhub \
MAILHUB_DEPLOY_BRANCH=main \
npm run deploy:remote

脚本会要求本地 HEAD 已推送到对应远端分支，然后在目标目录执行 git pull --ff-only、准备 Dovecot secret、离线同步证书、预拉取 Dovecot 镜像、迁移现有 Maildir、重建服务，并等待 app、postfix、dovecot 都进入健康状态。如果迁移写入或最终 SQLite 切换事务失败，脚本会清理未提交的 Maildir 文件并恢复切换前容器；切换事务一旦成功则不会自动启动 legacy 协议栈，以免已读、移动或删除状态在两个真源间分叉。此时若新服务启动失败，应保持 Maildir 数据不动并修复后向前恢复。目标工作区存在未提交变更时脚本会停止；确认可暂存远端工作区时，可显式设置 MAILHUB_DEPLOY_STASH_REMOTE=1。

配置 MAILHUB_CERT_SOURCE_DIR 后，发布脚本会先把主机证书复制为受控快照，再校验有效期、主机名和公私钥匹配。同步过程带并发锁和失败回滚，目标证书固定为 0644，私钥固定为 0640 并授权给容器运行组。证书变化后会同时重启 app 与 Dovecot，并通过 465、993 的 SNI、证书链、主机名和 SHA-256 指纹确认两个服务均已加载新证书。

同一脚本可由宝塔计划任务定期执行；宝塔仍负责申请和续期证书，MailHub 只读取续期结果：

cd "/opt/mailhub" && MAILHUB_CERT_RESTART=1 ./scripts/sync-tls-certificate.sh

默认验证公网语义端口 465 993，其中 993 会自动映射到 Dovecot 的 rootless 容器端口 31993。若部署明确关闭了其中一个 TLS 服务，可通过 MAILHUB_CERT_VERIFY_ENDPOINTS 调整；离线同步且无法检测 app 容器组时，必须显式设置 MAILHUB_CERT_READER_GID。

测试

npm test
npm run build

测试覆盖数据库迁移、多用户隔离、SMTP 凭据、API Token、DNS 服务商逻辑、DKIM、投递日志解析和前端纯逻辑模型。

安全清单

• 不要提交 .env、SQLite 数据库、API Token、SMTP 密码、DNS API 密钥、证书私钥或真实生产证书。
• 替换默认管理员凭据，设置足够长的 SESSION_SECRET。
• 生产发信前确认 SPF、DKIM、DMARC、PTR 和发信主机 A 记录。
• 确认服务器出站 25 端口没有被云厂商拦截。
• 确认入站 25/465/587/2525 以及所需的 110/143/993/995 已在云防火墙和系统防火墙放行。
• 新 IP 先小流量预热，避免突然大批量发送。
• 遵守适用法律、服务商政策和收件人同意要求；不要使用 MailHub 发送垃圾邮件。

贡献

欢迎提交 issue 和 pull request。开始前请阅读 CONTRIBUTING.md、CODE_OF_CONDUCT.md 和 SECURITY.md。

许可证

MailHub 使用 MIT License。详见 LICENSE。