v5.3.1

V5.3.1 更新说明

发布日期：2026-05-24

延续 V5.3.0 的渠道抽象，新增 Cyberpersons（CyberPanel Email Delivery）作为
第三个内置发件渠道。前端零改动，按发件人邮箱域名自动路由。

主要变更

1. 新增 Cyberpersons 渠道 src/email/providers/cyberpersons/

通过 Cyberpersons 官方 REST API（POST https://platform.cyberpersons.com/email/v1/send）
实现单封 / 批量发件，支持单密钥与多域名键值对/JSON 配置。

依托 CyberPanel 的 Cloudflare 集成，可一键自动配置发件域名的 SPF / DKIM / DMARC，
适合不想手动维护 DNS 的场景。完整接入流程见 Cyberpersons 配置教程。

2. 渠道路由规则扩展为三层

resolveProvider 在原有 SendFlare / Resend 链路末尾追加 Cyberpersons，保证
老部署行为完全不变：

1. SendFlare 键值对/JSON 命中 → SendFlare
2. Resend 键值对/JSON 命中 → Resend
3. Cyberpersons 键值对/JSON 命中 → Cyberpersons（新）
4. SendFlare 单密钥兜底
5. Resend 单密钥兜底
6. Cyberpersons 单密钥兜底（新）
7. 都没命中 → 抛错

3. 新增环境变量

CYBERPERSONS_API_KEY，格式与 RESEND_API_KEY / SENDFLARE_API_KEY 完全一致
（单密钥 / 键值对 / JSON）。同时识别别名 CYBERPERSONS_API_TOKEN 和
CYBERPERSONS，与 Resend 的多别名习惯一致。

4. Cyberpersons API 差异适配

Cyberpersons 的请求/响应结构与 Resend 有三处差异，已在 provider 内部消化，
对调用方完全透明：

差异点	Cyberpersons 行为	provider 内部处理
响应 id 位置	data.message_id（不是顶层 id）	内部抽取后仍返回 { id, raw }
to / cc / bcc	只接受单字符串，数组返 HTTP 500	数组取首个，与 SendFlare 行为一致
from 显示名	不接受 "Name <addr>"，需走独立 from_name 字段	自动从 fromName 或 RFC 5322 串中拆出
错误体结构	{ success:false, error:{ type, message } }	拼接成 "type: message" 抛出

5. /api/send/:id 系列端点扩展

GET / PATCH / /cancel 三个 Resend 特有端点，对 Cyberpersons 渠道发出的记录
返回 400「Cyberpersons 渠道暂不支持此操作」，与 SendFlare 的语义保持一致。

兼容性

• 老部署（仅配 Resend 或 SendFlare）行为 完全等价，无需任何调整
• DB schema 无变化，sent_emails.provider 列直接写入 'cyberpersons' 字面量
• 升级方式：拉代码 → wrangler deploy，无需迁移

已知限制

• 单封只能 1 个收件人，多收件人取数组首个；真实多发请走 /api/send/batch
• 暂未透传 tags / metadata（Cyberpersons 文档支持但项目内 payload 未产出）
• 不支持已发邮件的查询 / 修改 / 取消（同 SendFlare 限制）

---

历史版本见 README.md 版本历史表。

v5.3.0

V5.3.0 更新说明

发布日期：2026-05-23

发件能力的架构升级：把原来的单一 Resend 实现重构为可插拔的渠道抽象层，
并新增 SendFlare 作为第二个内置渠道。前端零改动，按发件人邮箱域名自动路由。

主要变更

1. 发件渠道抽象 src/email/providers/

src/email/providers/
├── shared.js              共用工具：三格式配置解析、域名匹配、payload 标准化
├── index.js               分发器：resolveProvider / sendEmailAuto / sendBatchAuto
├── resend/index.js        Resend 渠道（原 sender.js 迁移）
└── sendflare/index.js     SendFlare 渠道（新）

业务侧只 import providers/index.js 一个入口，未来加渠道不必再改业务代码。

2. 新增 SendFlare 渠道

基于 sendflare-sdk-ts@^1.0.5，纯 fetch 实现，兼容 Cloudflare Workers。

支持单封 / 批量发件、多域名密钥。不支持 查询已发邮件、修改 scheduled_at、
取消已调度邮件 —— 相关接口对 SendFlare 记录返回 400「SendFlare 渠道暂不支持此操作」。

3. 按域名自动路由

resolveProvider 的选择顺序（键值对永远优先于单密钥，避免裸 key 贪婪吞域名）：

1. SendFlare 键值对/JSON 命中 → SendFlare
2. Resend 键值对/JSON 命中 → Resend
3. SendFlare 单密钥兜底
4. Resend 单密钥兜底
5. 都没命中 → 抛错「未找到域名对应的发件 API Key: <domain>」

4. 数据库

sent_emails 表新增列：

provider TEXT NOT NULL DEFAULT 'resend'

老库首次启动通过 migrateSentEmailsFields 自动 ALTER TABLE 加列，无需手动迁移。

5. 新增环境变量

SENDFLARE_API_KEY，格式与 RESEND_API_KEY 完全一致（单密钥 / 键值对 / JSON）。
亦支持别名 SENDFLARE_TOKEN。

兼容性

• 仅配 RESEND_API_KEY 的老部署 行为完全等价，无需任何调整
• 升级方式：拉代码 → wrangler deploy，首次请求自动迁移 DB schema
• 验证迁移：wrangler d1 execute maill_free_db --command "PRAGMA table_info(sent_emails)"

二次开发：接入新渠道四步

1. 在 src/email/providers/yourprovider/index.js 实现
   sendEmailWithYourprovider(apiKey, payload) 与 sendBatchWithYourprovider，
   返回 { id, raw }；内部用 ../shared.js 的 normalizeSendPayload /
   selectKeyForDomain 保持入参语义统一
2. providers/index.js 注册命名空间，在 resolveProvider 与
   sendEmailAuto / sendBatchAuto 加分支
3. src/routes/api.js 的 baseOpts 增加 yourproviderApiKey: c.env.YOURPROVIDER_API_KEY || ''
4. 数据库不动 —— sent_emails.provider 直接写新值即可

前端、迁移逻辑都无需改动。

已知限制

• SendFlare SDK 错误粒度有限：HTTP 非 2xx 时仅抛 HTTP error! status: XXX，丢失服务端 message
• SendFlare SDK 的 to 是单字符串，主收件人若传数组只取第一个；cc/bcc 透传
• SendFlare 官方限流 5 req/s，批量超过请自行退避

---

历史版本见 README.md 版本历史表。

v5.2.2

v5.2.2

Bug 修复

• 修复普通用户可越权访问其他用户邮箱、邮箱配置和发件记录等安全问题
• 修复 admin 页面因权限设置不当无法访问的问题，添加超级管理员权限检查
• 修复 static asset 路径含 .html 后缀导致 Assets 307 重定向引发 500 错误
• 修复安全头设置方式，增强安全性

安全增强

• 使用 PBKDF2-SHA256 替代 SHA256 进行密码哈希，提升密码存储安全性
• 完善权限校验逻辑，防止越权操作

v5.2.1

引入 Hono 框架重构后端架构，优化邮件解析和验证码提取，暗色模式优化

v5.2.0

v5.2.0

新功能

• 引入 postal-mime 依赖，改进 HTML 和纯文本邮件内容的提取能力

Bug 修复

• 修复部分邮件客户端发送消息存在中文乱码的问题

v5.1.1 - 支持多种分隔符的邮箱别名规范化

v5.1.1 - 支持多种分隔符的邮箱别名规范化

本次更新

• 优化邮箱别名规范化逻辑，支持更多分隔符（+、_、-、.）
• 修复别名解析问题，提升识别准确性
• 优化邮箱显示逻辑

v5.0~5.1 更新总结

• 全新 UI 设计，引入深色模式支持
• 邮箱别名规范化识别与显示优化
• 多个 Bug 修复及性能优化

v5.1.0 - 邮箱别名规范化支持

邮箱别名规范化识别与显示优化

v5.0.1

V5.0.1 - 深色模式 Bug 修复

• 修复深色模式下侧边栏收起右侧显示异常的问题

---

v5.0

全新 UI 设计，深色模式支持

v4.8.1

🐛 Bug Fixes

• 修复邮箱信息加载错误

---

🚀 v4.8 完整更新日志

✨ 新增功能

• 邮件转发：支持将指定邮箱的邮件转发到目标邮箱
• 收藏功能：支持收藏单个邮箱
• 状态筛选：邮箱管理页面支持按转发/收藏状态筛选

📝 配置说明

⚠️ 转发的地址需要在 Cloudflare Email Addresses 中验证

FORWARD_RULES 环境变量配置

# 键值对格式
FORWARD_RULES="vip=a@example.com,news=b@example.com,*=fallback@example.com"

# JSON格式
FORWARD_RULES='[{"prefix":"vip","email":"a@example.com"},{"prefix":"*","email":"fallback@example.com"}]'

# 禁用转发
FORWARD_RULES="" 或 "disabled" 或 "none"

规则按前缀匹配，* 为兜底规则。转发目标邮箱必须在 Cloudflare 控制台中验证后才能使用。

🎨 页面展示

• 新增单个邮箱页的转发和收藏入口
• 邮箱列表支持查看转发状态和收藏状态
• 管理后台支持批量筛选操作