🇨🇳 中文 | 🌐 English
一个基于 Cloudflare Workers + D1 + R2 构建的前后端分离的开源临时邮箱服务,支持 RESTful API 调用,支持邮件接收、发送、转发等功能。
本仓库 fork 自 idinging/freemail,在其基础上将发件渠道统一为 Cloudflare Email Sending,新增站内系统设置(域名管理、访客开关),并移除多租户用户体系(仅保留管理员与访客)等改造。
本邮箱服务支持接收邮件时自动创建对应的邮箱,邮箱服务的转发目标邮箱地址需要在cloudflare Email Addresses中验证
📖 一键部署指南 | 🤖 Github Action 部署指南 | 📚 API 文档
| 首页 | 所有邮箱 |
|---|---|
![]() |
![]() |
| 单个邮箱登录 |
|---|
![]() |
| 类别 | 特性 |
|---|---|
| 📧 邮箱管理 | 随机生成临时邮箱 · 多域名支持 · 置顶/收藏 · 历史记录 · 邮箱搜索 |
| 💌 邮件功能 | 实时接收 · 自动刷新 · 验证码智能提取 · HTML/纯文本 · 邮件转发 |
| ✉️ 发件支持 | Cloudflare Email Sending 原生发件 · 批量发送 · 发件记录 |
| ⚙️ 站内设置 | 管理页在线维护邮箱域名列表 · 访客访问开关 · 配置状态检测 |
| ⚡ 技术架构 | Cloudflare Workers · D1 数据库 · R2 存储 · Email Routing |
| 版本 | 主要更新 |
|---|---|
| Fork 改造 | 发件渠道统一为 Cloudflare Email Sending(移除 Resend / SendFlare / Cyberpersons)· 新增站内系统设置(域名管理、访客开关)· 前端重构为中性极简双主题 · 移除多租户用户体系(仅保留管理员与访客) |
| V5.3.1(上游) | 新增 Cyberpersons(CyberPanel Email Delivery)发件渠道 |
| V5.3.0(上游) | 发件模块抽象为 providers · 新增 SendFlare 渠道 · 按发件人域名自动路由 · sent_emails 表新增 provider 字段 |
| V5.2.0 | 引入 postal-mime 改进邮件解析 · 修复部分客户端中文乱码问题 |
| V5.1.0 | 邮箱别名规范化支持扩展,支持 . + - 三种分隔符切分 |
| V1.0~v4.0 | 邮箱生成 · 邮件接收 · 验证码提取 · 用户管理后台 · R2 存储 EML |
- 一键部署:点击顶部按钮,按照 部署指南 完成配置
- 配置邮件路由(收件必需):域名 → Email Routing → Catch-all → 绑定 Worker
- 配置发件(可选):在 Cloudflare Dashboard → Email Service → Email Sending 完成发件域名 onboarding(需 Workers Paid 计划),Worker 通过
wrangler.toml的[[send_email]]绑定发送,无需第三方 API Key - 站内设置:部署后以管理员登录 → 系统设置,可在线维护邮箱域名列表与访客开关(数据库配置优先于
MAIL_DOMAIN环境变量)
使用 Git 集成部署时,请在 Workers → Settings → Variables 中手动配置环境变量
本地运行适合调试前端页面、管理接口和发件逻辑。真实收信依赖 Cloudflare Email Routing,仍需要部署到 Cloudflare Workers 后才能完整验证。
- 安装依赖
npm install- 配置本地变量
按需修改 wrangler.toml 中的 [vars]、D1 和 R2 绑定。至少建议设置:
ADMIN_NAME = "admin"
ADMIN_PASSWORD = "your_admin_password"
JWT_TOKEN = "your_random_jwt_secret"
MAIL_DOMAIN = "example.com"- 初始化本地 D1 数据库
npx wrangler d1 execute mail_free_db --local --file=./d1-init.sql如果你修改了 wrangler.toml 中的 database_name,请把上面的 mail_free_db 替换为你的数据库名称。
- 启动本地开发服务
npx wrangler dev启动后访问 Wrangler 输出的本地地址即可。默认管理员账号为 admin,密码使用 ADMIN_PASSWORD。
| 变量名 | 说明 | 必需 |
|---|---|---|
| TEMP_MAIL_DB | D1 数据库绑定 | 是 |
| MAIL_EML | R2 存储桶绑定 | 是 |
Email Sending 发件绑定(wrangler.toml 的 [[send_email]]) |
发件时必需 | |
| MAIL_DOMAIN | 邮箱域名,多个用逗号分隔;站内「系统设置」的域名列表优先,此变量为回退值 | 是 |
| ADMIN_PASSWORD | 严格管理员密码 | 是 |
| ADMIN_NAME | 严格管理员用户名(默认 admin) |
否 |
| JWT_TOKEN | JWT 签名密钥 | 是 |
| GUEST_PASSWORD | 访客账号密码;未设置则访客无法登录(还可在系统设置中关闭访客入口) | 否 |
| SESSION_EXPIRE_DAYS | 会话过期天数(默认 7) | 否 |
| FORWARD_RULES | 邮件转发规则 | 否 |
发件说明(Cloudflare Email Sending)
发件通过 Cloudflare Email Sending 的 Workers 绑定完成,不再依赖任何第三方发件平台:
- 需要 Workers Paid 计划
- 发件域名需在 Cloudflare Dashboard → Email Service → Email Sending 完成 onboarding
wrangler.toml中保留[[send_email]]绑定(绑定名EMAIL)- 支持
cc/bcc/replyTo/headers/attachments,不支持定时发送 - 本地
wrangler dev若使用远程绑定(remote = true),需要设置CLOUDFLARE_API_TOKEN
FORWARD_RULES 配置格式
规则按前缀匹配,* 为兜底规则。
- 进入 Cloudflare 控制台 → 域名 → 电子邮件 → 电子邮件路由
- 切换到「目标地址」选项卡
- 点击「添加目标地址」,输入转发目标邮箱
- 前往目标邮箱收取验证邮件并点击确认链接
# 键值对格式
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"常见问题
- 邮件接收不到:检查 Email Routing 配置、MX 记录、站内系统设置或 MAIL_DOMAIN 变量中的域名列表
- 邮件发送失败:确认发件域名已完成 Email Sending onboarding、账号为 Workers Paid 计划、
[[send_email]]绑定存在 - 数据库连接错误:确认 D1 绑定名为
TEMP_MAIL_DB,检查 database_id - 登录问题:确认 ADMIN_PASSWORD 和 JWT_TOKEN 已设置,清除浏览器缓存
- 界面显示异常:检查静态资源路径,查看浏览器控制台错误
调试技巧
# 本地调试
wrangler dev
# 查看实时日志
wrangler tail
# 检查数据库
wrangler d1 execute TEMP_MAIL_DB --command "SELECT * FROM mailboxes LIMIT 10"- 静态资源缓存:更新后在 Cloudflare 控制台 Purge Everything,浏览器强制刷新
- R2/D1 费用:有免费额度限制,建议定期清理过期邮件
- 安全:生产环境务必修改默认的
ADMIN_PASSWORD和JWT_TOKEN
本项目支持 GitHub Actions 自动部署到 Cloudflare Workers。详细配置说明请参考 自动部署指南。
本项目基于 idinging/freemail 开发。
感谢 sarsanta 贡献的 GitHub Actions 自动部署功能!
感谢 oxygen 贡献的权限越权漏洞及其修复
Apache-2.0 license



