临时邮箱系统后端 API (TempMail Backend API)

一个功能完善的临时邮箱后端服务，提供 REST API、SMTP 邮件接收和 WebSocket 实时推送功能。专注于后端开发，可与任何前端框架集成。

⚠️ 重要安全说明

本系统是临时邮箱服务，仅用于接收邮件，禁止对外发送邮件。

🔒 安全特性

✅ 只接收邮件 - SMTP 服务器只接收发送到本系统邮箱的邮件
✅ 严格地址验证 - 只有系统内的邮箱/别名才能接收邮件
✅ 防止邮件中继 - 拒绝所有发往外部地址的邮件（返回 550 错误）
❌ 不支持对外发送 - 没有实现任何邮件发送功能
❌ 不会成为垃圾邮件中继 - 通过严格的收件人验证防止滥用

适用场景：临时邮箱、一次性邮箱、邮件测试、匿名接收等

🎯 项目状态

当前版本: v0.8.2-beta 架构: 纯后端 API 服务（无前端） 开发进度: 100%（后端核心功能已全部完成，响应格式已标准化）

✅ 已完成功能

✅ 完整的 REST API - 用户、邮箱、邮件管理
✅ SMTP 邮件接收 - 基于 go-smtp，实时接收外部邮件
✅ JWT 认证系统 - 双令牌机制（访问令牌 + 刷新令牌）
✅ WebSocket 实时推送 - 新邮件即时通知
✅ 管理后台 API - 用户管理、域名管理、系统统计
✅ 角色权限系统 - RBAC（User/Admin/Super）三级权限
✅ 自动清理机制 - 定时清理过期邮箱和邮件
✅ 邮箱 Token 保护 - 游客邮箱访问控制
✅ 邮件附件支持 - MIME 多部分解析、附件上传下载
✅ 邮箱别名系统 - 多地址绑定、SMTP 别名路由、API 完整支持
✅ 用户域名管理 - 自定义域名、DNS 验证、共享/独享模式、MX 配置
✅ 技术栈优化 - 使用最新成熟库，避免重复造轮子
✅ 生产环境就绪 - 完整的监控、日志、健康检查系统
✅ 兼容API接口 - 提供 mail.ry.edu.kg 风格API，第三方系统可直接对接

🎯 最新更新 (v0.8.2-beta)

重大改进：兼容API完全兼容 mail.ry.edu.kg

✅ 兼容API格式调整 - 所有兼容API端点使用旧格式
- 直接返回数据对象，不包装
- 错误响应使用 {error: "..."} 格式
- 与 mail.ry.edu.kg 100%兼容
- 第三方系统可无缝对接
- 详见：API兼容层说明

v0.8.0 重大改进：统一API响应格式

✅ 面向失败设计 - 采用统一的 {code, msg, data} 响应格式
- 标准业务状态码
- 中文错误消息
- 更清晰的成功/失败判断
- 详见：API响应格式说明
✅ 向后兼容 - 兼容API保持旧格式不变
✅ 开发体验优化 - 统一的错误处理，降低前端集成复杂度

响应示例：

{
  "code": 200,
  "msg": "成功",
  "data": {
    "id": "mailbox-123",
    "address": "test@temp.mail"
  }
}

🚀 技术栈优化 (v0.7.0-beta)

✅ 数据库迁移系统 - 使用 golang-migrate/migrate 专业迁移工具
- 支持版本化数据库迁移
- 支持回滚操作
- 生产环境安全迁移
✅ 限流系统优化 - 使用 golang.org/x/time/rate 令牌桶算法
- 更平滑的限流控制
- 支持突发流量处理
- 自适应限流（根据用户等级）
✅ 日志系统增强 - 支持日志轮转和结构化配置
- 自动日志轮转
- 日志压缩
- 按大小和时间轮转
✅ 健康检查标准化 - 使用 heptiolabs/healthcheck 标准库
- 标准化健康检查接口
- 支持 Kubernetes 探针
- 多维度健康检查
✅ 监控系统优化 - 使用官方 Prometheus 客户端
- 标准化 Prometheus 指标
- 自动指标注册
- HTTP 指标导出端点
✅ 邮件解析增强 - 使用 jhillyerd/enmime 专业 MIME 解析库
- 更强大的 MIME 解析
- 更好的附件处理
- 支持复杂邮件格式
✅ 兼容API接口 - 提供标准化的第三方对接API
- 兼容 mail.ry.edu.kg 风格API格式
- API Key认证机制
- 支持分页查询
- 完整的错误处理
- 详细的接口文档

🔧 待实现功能

🔄 邮件转发规则
📈 高级分析报表

🏗️ 技术架构

技术栈

语言: Go 1.25
Web 框架: Gin v1.11.0
SMTP: go-smtp v0.24.0
WebSocket: gorilla/websocket v1.5.3
认证: JWT (golang-jwt/jwt/v5)
密码加密: bcrypt
配置管理: Viper
日志: Zap
存储: 内存存储（开发）/ PostgreSQL + Redis（生产）

🚀 快速开始

开发环境启动

cd backend

# 设置必需的环境变量
export TEMPMAIL_JWT_SECRET="test-secret-key-for-development-32-chars-long-at-least"

# 启动综合服务（HTTP + SMTP + WebSocket）
go run ./cmd/server

# 服务运行在:
# - HTTP API: http://localhost:8080
# - SMTP Server: localhost:25
# - WebSocket: ws://localhost:8080/v1/ws

Docker 部署

# 构建镜像
docker build -t tempmail-backend ./backend

# 运行容器
docker run -d \
  -p 8080:8080 \
  -p 25:25 \
  -e TEMPMAIL_JWT_SECRET="your-super-secret-jwt-key-at-least-32-chars" \
  tempmail-backend

📖 API 文档

认证相关

# 用户注册
POST /v1/auth/register
{
  "email": "user@example.com",
  "password": "password123",
  "username": "myname"
}

# 用户登录
POST /v1/auth/login
{
  "email": "user@example.com",
  "password": "password123"
}

# 刷新令牌
POST /v1/auth/refresh
{
  "refreshToken": "..."
}

# 获取当前用户信息
GET /v1/auth/me
Authorization: Bearer <access_token>

邮箱管理

# 创建临时邮箱（游客模式）
POST /v1/mailboxes
Response:
{
  "id": "uuid",
  "address": "random@temp.mail",
  "token": "mailbox-access-token",
  "expiresAt": "2024-01-01T00:00:00Z"
}

# 创建临时邮箱（认证用户）
POST /v1/mailboxes
Authorization: Bearer <access_token>
{
  "prefix": "custom",
  "domain": "temp.mail"
}

# 获取邮箱列表（仅认证用户）
GET /v1/mailboxes
Authorization: Bearer <access_token>

# 查看邮箱详情
GET /v1/mailboxes/:id
X-Mailbox-Token: <mailbox_token>

# 删除邮箱
DELETE /v1/mailboxes/:id
X-Mailbox-Token: <mailbox_token>

邮件管理

# 获取邮件列表
GET /v1/mailboxes/:id/messages
X-Mailbox-Token: <mailbox_token>

# 查看邮件详情
GET /v1/mailboxes/:id/messages/:messageId
X-Mailbox-Token: <mailbox_token>

# 标记邮件为已读
POST /v1/mailboxes/:id/messages/:messageId/read
X-Mailbox-Token: <mailbox_token>

# 下载邮件附件
GET /v1/mailboxes/:id/messages/:messageId/attachments/:attachmentId
X-Mailbox-Token: <mailbox_token>

邮箱别名管理

# 创建邮箱别名
POST /v1/mailboxes/:id/aliases
X-Mailbox-Token: <mailbox_token>
{
  "address": "alias@temp.mail"
}

# 列出邮箱别名
GET /v1/mailboxes/:id/aliases
X-Mailbox-Token: <mailbox_token>

# 获取别名详情
GET /v1/mailboxes/:id/aliases/:aliasId
X-Mailbox-Token: <mailbox_token>

# 切换别名状态（启用/禁用）
PATCH /v1/mailboxes/:id/aliases/:aliasId
X-Mailbox-Token: <mailbox_token>
{
  "isActive": false
}

# 删除别名
DELETE /v1/mailboxes/:id/aliases/:aliasId
X-Mailbox-Token: <mailbox_token>

用户域名管理

# 添加自定义域名
POST /v1/user-domains
Authorization: Bearer <access_token>
{
  "domain": "yourdomain.com",
  "mode": "shared"  # shared 或 exclusive
}

# 列出我的域名
GET /v1/user-domains
Authorization: Bearer <access_token>

# 获取域名详情
GET /v1/user-domains/:id
Authorization: Bearer <access_token>

# 验证域名所有权（DNS TXT 记录）
POST /v1/user-domains/:id/verify
Authorization: Bearer <access_token>

# 获取 MX 配置说明
GET /v1/user-domains/:id/setup
Authorization: Bearer <access_token>

# 切换域名模式（共享/独享）
PUT /v1/user-domains/:id/mode
Authorization: Bearer <access_token>
{
  "mode": "exclusive"
}

# 删除域名
DELETE /v1/user-domains/:id
Authorization: Bearer <access_token>

WebSocket 实时推送

// 连接 WebSocket
const ws = new WebSocket('ws://localhost:8080/v1/ws');

// 订阅邮箱
ws.send(JSON.stringify({
  type: 'subscribe',
  mailboxId: 'mailbox-uuid',
  token: 'mailbox-token'
}));

// 接收新邮件通知
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'new_mail') {
    console.log('New mail received:', data);
  }
};

管理 API（需要管理员权限）

# 用户管理
GET    /v1/admin/users              # 列出用户（Admin权限）
GET    /v1/admin/users/:id          # 获取用户详情（Admin权限）
PATCH  /v1/admin/users/:id          # 更新用户（Admin权限）
DELETE /v1/admin/users/:id          # 删除用户（Super权限）

# 配额管理
GET    /v1/admin/users/:id/quota    # 获取配额（Admin权限）
PUT    /v1/admin/users/:id/quota    # 更新配额（Admin权限）

# 域名管理
GET    /v1/admin/domains            # 列出域名（Admin权限）
POST   /v1/admin/domains            # 添加域名（Super权限）
DELETE /v1/admin/domains/:domain    # 删除域名（Super权限）

# 系统统计
GET    /v1/admin/statistics         # 系统统计（Admin权限）

兼容API（第三方对接）

本系统提供 mail.ry.edu.kg 风格的API接口，第三方系统可直接对接使用。

# 获取系统配置
GET /api/config
X-API-Key: YOUR_API_KEY

# 生成临时邮箱
POST /api/emails/generate
X-API-Key: YOUR_API_KEY
{
  "name": "test",
  "expiryTime": 3600000,  # 1小时，单位毫秒
  "domain": "temp.mail"
}

# 获取邮箱列表
GET /api/emails?cursor=0&limit=20
X-API-Key: YOUR_API_KEY

# 获取邮件列表
GET /api/emails/{emailId}?cursor=0&limit=20
X-API-Key: YOUR_API_KEY

# 获取单封邮件
GET /api/emails/{emailId}/{messageId}
X-API-Key: YOUR_API_KEY

对接优势:

✅ 标准化API格式，易于集成
✅ 完整的API文档
✅ API Key认证
✅ 支持分页查询
✅ 开源免费，数据私有

详细文档请查看：API兼容层说明

📁 项目结构

tempmail/
├── backend/
│   ├── cmd/
│   │   ├── server/         # 综合服务入口（HTTP + SMTP + WebSocket）
│   │   └── api/            # 仅 HTTP API 服务
│   ├── internal/
│   │   ├── auth/           # 认证服务和 JWT
│   │   ├── config/         # 配置管理（Viper）
│   │   ├── domain/         # 领域模型和接口
│   │   ├── logger/         # 日志系统（Zap）
│   │   ├── middleware/     # HTTP 中间件
│   │   ├── service/        # 业务逻辑层
│   │   ├── smtp/           # SMTP 服务器
│   │   ├── storage/        # 存储实现
│   │   │   ├── memory/     # 内存存储（开发）
│   │   │   └── hybrid/     # 混合存储（生产预留）
│   │   ├── transport/      # 传输层（HTTP）
│   │   └── websocket/      # WebSocket 实时推送
│   └── migrations/         # 数据库迁移脚本
├── docs/                   # 项目文档
├── deploy/                 # 部署配置
└── CLAUDE.md              # Claude Code 工作指南

🔧 配置说明

环境变量

# JWT 密钥（生产环境必须修改，至少32字符）
TEMPMAIL_JWT_SECRET=your-super-secret-jwt-key-at-least-32-chars

# HTTP 服务器
TEMPMAIL_SERVER_HOST=0.0.0.0
TEMPMAIL_SERVER_PORT=8080

# SMTP 服务
TEMPMAIL_SMTP_BIND_ADDR=:25
TEMPMAIL_SMTP_DOMAIN=temp.mail

# 邮箱配置
TEMPMAIL_MAILBOX_ALLOWED_DOMAINS=temp.mail,tempmail.dev
TEMPMAIL_MAILBOX_DEFAULT_TTL=24h

# CORS（可选，用于前端接入）
TEMPMAIL_CORS_ALLOWED_ORIGINS=http://localhost:3000

# 日志
TEMPMAIL_LOG_LEVEL=info
TEMPMAIL_LOG_DEVELOPMENT=false

# 数据库（生产环境）
TEMPMAIL_DATABASE_DSN=postgres://user:pass@host:5432/dbname

# Redis（生产环境）
TEMPMAIL_REDIS_ADDRESS=redis:6379
TEMPMAIL_REDIS_PASSWORD=your-redis-password

🧪 开发指南

后端开发

cd backend

# 安装依赖
go mod download

# 运行服务（仅 HTTP）
go run ./cmd/api

# 运行服务（HTTP + SMTP + WebSocket）
go run ./cmd/server

# 运行测试
go test ./...

# 构建生产版本
go build -o server ./cmd/server

测试 SMTP

# 使用 swaks 测试
swaks --to test@temp.mail --server localhost:25 --ehlo localhost

# 使用 telnet
telnet localhost 25
HELO localhost
MAIL FROM:<sender@example.com>
RCPT TO:<test@temp.mail>
DATA
Subject: Test
This is a test email.
.
QUIT

测试 API

# 健康检查
curl http://localhost:8080/health

# 创建邮箱
curl -X POST http://localhost:8080/v1/mailboxes

# 使用返回的 token 查看邮箱
curl -H "X-Mailbox-Token: <token>" \
     http://localhost:8080/v1/mailboxes/<id>/messages

🔐 安全建议

⚠️ JWT 密钥 - 生产环境必须使用强密钥（至少32字符）
🔑 密码策略 - 实施强密码要求
🔒 HTTPS - 生产环境必须使用 SSL/TLS
🚫 端口限制 - 不要暴露 SMTP 端口到公网（使用防火墙）
💾 数据加密 - 敏感数据应加密存储
📝 审计日志 - 记录所有管理操作
🔄 定期更新 - 及时更新依赖包

📚 文档

API 参考文档 - 完整的 API 端点说明（34+ 个端点）
部署指南 - 详细的部署步骤和配置
更新日志 - 版本更新记录
开发指南 - Claude Code 工作指南和安全原则
技术架构 - 详细的技术栈说明
安装指南 - 安装和配置指南
产品需求 - 产品需求文档
路线图 - 项目发展路线图

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

Fork 本仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

Gin - Web 框架
go-smtp - SMTP 服务器
gorilla/websocket - WebSocket 库
Zap - 日志库
JWT - JWT 认证
Viper - 配置管理

⭐ 如果觉得这个项目有帮助，请给个 Star！

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
.factory/droids		.factory/droids
.github/workflows		.github/workflows
backend		backend
deploy		deploy
docs		docs
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
start-backend.ps1		start-backend.ps1
start.bat		start.bat
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation

临时邮箱系统后端 API (TempMail Backend API)

⚠️ 重要安全说明

🔒 安全特性

🎯 项目状态

✅ 已完成功能

🎯 最新更新 (v0.8.2-beta)

🚀 技术栈优化 (v0.7.0-beta)

🔧 待实现功能

🏗️ 技术架构

技术栈

🚀 快速开始

开发环境启动

Docker 部署

📖 API 文档

认证相关

邮箱管理

邮件管理

邮箱别名管理

用户域名管理

WebSocket 实时推送

管理 API（需要管理员权限）

兼容API（第三方对接）

📁 项目结构

🔧 配置说明

环境变量

🧪 开发指南

后端开发

测试 SMTP

测试 API

🔐 安全建议

📚 文档

🤝 贡献指南

📄 许可证

🙏 致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages