MailFoundry：从零构建邮件投递系统

一项目概述

MailFoundry 是一个面向学习、实验和开源探索的 mail server 项目。它不是直接包装成熟邮件服务，而是把邮件系统背后的协议、投递链路、可信度机制和工程实现拆开讲清楚，并提供一个可本地运行、可 Docker 部署的 Go 原型服务。

邮件系统看起来只是"发一封邮件"，但真正跑起来会涉及很多层：

MUA / MTA / MDA 的角色分工
SMTP 命令流和状态机
MX / A / AAAA / TXT / PTR 等 DNS 记录
PTR / SPF / DKIM / DMARC 信任模型
STARTTLS 与 SMTP over TLS 传输安全
附件、HTML、内联图片和 MIME 结构
队列、重试、限流、灰名单和投递状态
本地测试、relay 代发、direct MX 投递

二核心能力

能力	说明
HTTP API 接收邮件	统一入口接收邮件发送请求
异步队列与 Worker	进程内异步队列和 worker 投递
三种投递模式	`spool`（本地落盘）、`relay`（中继代发）、`direct`（直连 MX）
MIME 邮件构造	支持纯文本、HTML、附件和内联图片
DKIM 签名	可选 DKIM 签名支持
本地限流与灰名单	防止滥用和灰名单机制
投递状态查询	支持查询邮件投递状态
Docker 支持	可容器化部署

三快速开始

1、环境准备

需要安装 Go 1.22+：

go version

2、启动服务

git clone https://github.com/victorxia850/mail-foundry.git
cd mail-foundry
go run ./cmd/mailfoundry

默认监听：http://localhost:8080

3、发送测试邮件

curl -X POST http://localhost:8080/messages/send.json \
  -H 'Content-Type: application/json' \
  -H 'X-Zm-Trackingid: local-test-1' \
  -d '{
    "applicationID": "local",
    "engine": "mailfoundry",
    "message": {
      "from_email": "sender@example.com",
      "from_name": "Sender",
      "to": [{"email": "2358114512@qq.com"}],
      "subject": "Hello from MailFoundry",
      "text": "hello",
      "html": "<p>hello</p>"
    }
  }'

4、查看本地邮件文件

默认 spool 模式会生成 .eml 文件：

ls data/spool

四项目结构

mail-foundry/
├── cmd/
│   └── mailfoundry/          # 服务启动入口
├── internal/
│   ├── app/                  # HTTP 路由、中间件、API 处理
│   ├── config/               # 环境变量配置加载
│   ├── core/                 # 消息模型、队列、状态、限流和灰名单
│   └── delivery/             # MIME 构造、DKIM、SMTP 投递和 spool 落盘
├── docs/                     # 邮件系统知识库
│   ├── 01-foundations/       # 邮件基础
│   ├── 02-authentication/    # 邮件认证 (SPF/DKIM/DMARC)
│   ├── 03-transport-security/# 传输安全 (STARTTLS)
│   └── 04-operations/        # 运维文档
├── configs/                  # 配置样例
├── go.mod
├── Dockerfile
└── README.md

五投递模式

模式	是否真实发信	是否需要外部 SMTP	推荐场景
`spool`	否	否	本地开发、验证 MIME、检查 `.eml` 内容
`relay`	是	是	通过 QQ 邮箱、企业邮箱、SES、SendGrid 等服务代发
`direct`	是	否	查询 MX 后直连收件方 SMTP，适合学习和实验

1、 spool 模式（默认）

export MF_DELIVERY_MODE=spool
export MF_SPOOL_DIR=data/spool
go run ./cmd/mailfoundry

2、 relay 模式

export MF_DELIVERY_MODE=relay
export MF_SMTP_TARGET=smtp.example.com:587
export MF_STARTTLS_POLICY=mandatory
go run ./cmd/mailfoundry

3、 direct 模式

export MF_DELIVERY_MODE=direct
export MF_SMTP_PORT=25
export MF_STARTTLS_POLICY=opportunistic
go run ./cmd/mailfoundry

六配置说明

变量	默认值	说明
`MF_HTTP_ADDR`	`:8080`	HTTP 服务监听地址
`MF_DELIVERY_MODE`	`spool`	投递模式
`MF_SPOOL_DIR`	`data/spool`	`.eml` 文件保存目录
`MF_WORKERS`	`4`	异步投递 worker 数量
`MF_QUEUE_SIZE`	`1024`	本地队列大小
`MF_SMTP_TARGET`	空	relay 目标或固定 SMTP 目标
`MF_SMTP_PORT`	`25`	direct 模式连接 MX 端口
`MF_STARTTLS_POLICY`	`opportunistic`	STARTTLS 策略
`MF_RCPT_PER_MINUTE`	`30`	单个收件人每分钟投递限制
`MF_GREYLIST_THRESHOLD`	`3`	触发灰名单的失败次数
`MF_DKIM_PRIVATE_KEY_FILE`	空	DKIM 私钥文件路径

七 Docker 运行

# 构建镜像
docker build -t mailfoundry .

# 运行服务
docker run --rm -p 8080:8080 mailfoundry

# 挂载 spool 目录
docker run --rm -p 8080:8080 \
  -v "$PWD/data/spool:/app/data/spool" \
  mailfoundry

八文档地图

建议按下面顺序阅读：

九技术栈

技术	用途
Go	HTTP 服务、异步队列、SMTP 投递
net/smtp	SMTP 客户端基础能力
net	MX 查询、TCP 连接
crypto/rsa	DKIM RSA 签名
Docker	容器化运行
Markdown	邮件系统知识库

十学习路径建议

1、初学者路径

阅读 foundations 文档：理解 MUA、MTA、MDA、SMTP、MX 和 DNS
阅读 authentication 文档：理解 PTR、SPF、DKIM、DMARC 如何建立发信可信度
阅读 transport security 文档：理解 STARTTLS 和 SMTP over TLS 解决的问题
启动 Go 服务：用 spool 模式提交邮件并检查 .eml 内容
尝试真实投递：使用 relay 或 direct 模式，观察真实 SMTP 投递

2、进阶方向

补充 SMTP AUTH，让 relay 模式支持账号和授权码
补充持久化队列，替换当前进程内队列
增加重试策略和退避算法
增加更完整的投递报告
增加 DKIM 公钥生成和 DNS 配置辅助工具
增加 Prometheus 或 OpenTelemetry 可观测性
增加集成测试和本地 SMTP mock server

十一适合谁

想系统理解邮件系统的人
想学习 SMTP、DNS、DKIM、DMARC 的工程师
想自己实现 mail server 或 mail infrastructure 的开发者
想从协议走到代码实现的学习者
想搭建本地邮件投递实验环境的人

十二参考资源

十三当前状态

项目当前处于原型阶段：

已完成：

知识库主线已经初步形成
Go 原型服务可以本地运行
Docker 镜像可以构建和启动
默认 spool 模式可以稳定验证
relay 和 direct 模式具备基础链路

待完善：

SMTP AUTH
持久化队列
重试和死信机制
更完整的安全策略
更强的可观测性
生产级配置管理
投递质量治理
更完整的自动化测试

十四贡献与反馈

欢迎围绕下面方向继续完善：

协议文档勘误和补充
SMTP AUTH 和 relay 能力
DKIM、SPF、DMARC 配置工具
本地 SMTP mock server
投递报告和状态模型
队列、重试、限流和灰名单
Docker Compose 示例
测试用例和 CI
运维和 deliverability 文档

十五声明

MailFoundry 适合学习和实验，不建议直接用于生产发信。

真实邮件投递涉及发信信誉、反垃圾策略、DNS 认证、密钥治理、滥用防护、合规和可观测性。生产环境应谨慎评估，并优先使用成熟邮件基础设施或经过充分验证的部署方案。

MailFoundry：从零构建邮件投递系统

一项目概述

二核心能力

三快速开始

1、环境准备

2、启动服务

3、发送测试邮件

4、查看本地邮件文件

四项目结构

五投递模式

1、 spool 模式（默认）

2、 relay 模式

3、 direct 模式

六配置说明

七 Docker 运行

八文档地图

九技术栈

十学习路径建议

1、初学者路径

2、进阶方向

十一适合谁

十二参考资源

十三当前状态

十四贡献与反馈

十五声明

◆AI Assistant

◆Comments (0)

一 项目概述

二 核心能力

三 快速开始

1、 环境准备

2、 启动服务

3、 发送测试邮件

4、 查看本地邮件文件

四 项目结构

五 投递模式

1、 spool 模式（默认）

2、 relay 模式

3、 direct 模式

六 配置说明

七 Docker 运行

八 文档地图

九 技术栈

十 学习路径建议

1、 初学者路径

2、 进阶方向

十一 适合谁

十二 参考资源

十三 当前状态

十四 贡献与反馈

十五 声明

◆AI Assistant

◆Comments (0)

一项目概述

二核心能力

三快速开始

1、环境准备

2、启动服务

3、发送测试邮件

4、查看本地邮件文件

四项目结构

五投递模式

六配置说明

八文档地图

九技术栈

十学习路径建议

1、初学者路径

2、进阶方向

十一适合谁

十二参考资源

十三当前状态

十四贡献与反馈

十五声明