Skip to content
This repository was archived by the owner on Nov 14, 2026. It is now read-only.
GuccbaiPublic archive
forked from idinging/freemail

About

Cloudflare 域名邮箱系统 临时邮箱系统 domain mail tempmail

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Freemail - 临时邮箱服务

Deploy to Cloudflare Workers

🇨🇳 中文 | 🌐 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

部署配置

快速开始

  1. 一键部署:点击顶部按钮,按照 部署指南 完成配置
  2. 配置邮件路由(收件必需):域名 → Email Routing → Catch-all → 绑定 Worker
  3. 配置发件(可选):在 Cloudflare Dashboard → Email Service → Email Sending 完成发件域名 onboarding(需 Workers Paid 计划),Worker 通过 wrangler.toml 的 [[send_email]] 绑定发送,无需第三方 API Key
  4. 站内设置:部署后以管理员登录 → 系统设置,可在线维护邮箱域名列表与访客开关(数据库配置优先于 MAIL_DOMAIN 环境变量)

使用 Git 集成部署时,请在 Workers → Settings → Variables 中手动配置环境变量

本地运行

本地运行适合调试前端页面、管理接口和发件逻辑。真实收信依赖 Cloudflare Email Routing,仍需要部署到 Cloudflare Workers 后才能完整验证。

  1. 安装依赖
npm install
  1. 配置本地变量

按需修改 wrangler.toml 中的 [vars]、D1 和 R2 绑定。至少建议设置:

ADMIN_NAME = "admin"
ADMIN_PASSWORD = "your_admin_password"
JWT_TOKEN = "your_random_jwt_secret"
MAIL_DOMAIN = "example.com"
  1. 初始化本地 D1 数据库
npx wrangler d1 execute mail_free_db --local --file=./d1-init.sql

如果你修改了 wrangler.toml 中的 database_name,请把上面的 mail_free_db 替换为你的数据库名称。

  1. 启动本地开发服务
npx wrangler dev

启动后访问 Wrangler 输出的本地地址即可。默认管理员账号为 admin,密码使用 ADMIN_PASSWORD。

环境变量

变量名 说明 必需
TEMP_MAIL_DB D1 数据库绑定 是
MAIL_EML R2 存储桶绑定 是
EMAIL 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 绑定完成,不再依赖任何第三方发件平台:

  1. 需要 Workers Paid 计划
  2. 发件域名需在 Cloudflare Dashboard → Email Service → Email Sending 完成 onboarding
  3. wrangler.toml 中保留 [[send_email]] 绑定(绑定名 EMAIL)
  4. 支持 cc / bcc / replyTo / headers / attachments,不支持定时发送
  5. 本地 wrangler dev 若使用远程绑定(remote = true),需要设置 CLOUDFLARE_API_TOKEN
FORWARD_RULES 配置格式

规则按前缀匹配,* 为兜底规则。

⚠️ 重要:转发目标邮箱必须在 Cloudflare 控制台中验证后才能使用:

  1. 进入 Cloudflare 控制台 → 域名 → 电子邮件 → 电子邮件路由
  2. 切换到「目标地址」选项卡
  3. 点击「添加目标地址」,输入转发目标邮箱
  4. 前往目标邮箱收取验证邮件并点击确认链接

转发目标地址验证

# 键值对格式
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"

故障排除

常见问题
  1. 邮件接收不到:检查 Email Routing 配置、MX 记录、站内系统设置或 MAIL_DOMAIN 变量中的域名列表
  2. 邮件发送失败:确认发件域名已完成 Email Sending onboarding、账号为 Workers Paid 计划、[[send_email]] 绑定存在
  3. 数据库连接错误:确认 D1 绑定名为 TEMP_MAIL_DB,检查 database_id
  4. 登录问题:确认 ADMIN_PASSWORD 和 JWT_TOKEN 已设置,清除浏览器缓存
  5. 界面显示异常:检查静态资源路径,查看浏览器控制台错误
调试技巧
# 本地调试
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 贡献的权限越权漏洞及其修复

Star History

Star History Chart

许可证

Apache-2.0 license

About

Cloudflare 域名邮箱系统 临时邮箱系统 domain mail tempmail

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages