Once Mail

一次性临时邮箱服务，基于 Go 语言开发。用户无需注册即可获取临时邮箱地址，通过 WebSocket 实时接收邮件。

功能特性

• 实时邮件推送 — 通过 WebSocket 即时接收邮件，无需刷新页面
• 内置 SMTP 服务器 — 直接接收邮件，无需依赖第三方邮件服务
• 临时邮箱地址 — 自动生成随机地址，也支持自定义前缀
• HTML 邮件渲染 — 同时支持 HTML 和纯文本邮件内容展示
• 关键词黑名单 — 可配置保留邮箱前缀（如 admin、postmaster 等）
• 轻量部署 — 单二进制文件 + 静态前端，支持 Docker 一键部署
• 前端可定制 — 支持挂载自定义静态资源替换默认 Web 页面

快速开始

环境要求

• Go 1.22+

本地运行

go mod download
go build -o once-mail ./cmd/server
./once-mail -config config.json

服务启动后：

• HTTP 服务：http://localhost:3000
• SMTP 服务：端口 25

Docker 部署

Docker 镜像通过 GitHub Actions 自动构建并发布到 GitHub Container Registry：

ghcr.io/xpnas/once-mail

使用预构建镜像运行：

docker run -d \
  --name once-mail \
  -p 25:25 \
  -p 3000:3000 \
  -v $(pwd)/config.json:/app/config.json \
  ghcr.io/xpnas/once-mail:master

自定义 Web 页面：

将自定义的前端静态资源目录挂载到容器内的 /app/public，即可替换默认页面：

docker run -d \
  --name once-mail \
  -p 25:25 \
  -p 3000:3000 \
  -v $(pwd)/config.json:/app/config.json \
  -v $(pwd)/my-public:/app/public \
  ghcr.io/xpnas/once-mail:master

自定义目录中至少需要包含 index.html，完整结构可参考项目 public/ 目录。

从源码构建运行：

docker build -t once-mail .
docker run -d \
  --name once-mail \
  -p 25:25 \
  -p 3000:3000 \
  -v $(pwd)/config.json:/app/config.json \
  once-mail

Docker Compose 部署

创建 docker-compose.yml：

services:
  once-mail:
    image: ghcr.io/xpnas/once-mail:master
    container_name: once-mail
    restart: unless-stopped
    ports:
      - "25:25"
      - "3000:3000"
    volumes:
      - ./config.json:/app/config.json
      # 可选：挂载自定义前端资源
      # - ./my-public:/app/public

启动服务：

docker compose up -d

配置说明

编辑 config.json：

{
  "mailin": {
    "host": "0.0.0.0",
    "port": 25
  },
  "httpPort": 3000,
  "domain": "your-domain.com",
  "publicDir": "public",
  "keywordBlackList": ["admin", "postmaster", "system", "webmaster"]
}

字段	说明	默认值
mailin.host	SMTP 监听地址	0.0.0.0
mailin.port	SMTP 监听端口	25
httpPort	HTTP 服务端口	3000
domain	邮箱域名	localhost
publicDir	静态资源目录路径	public
keywordBlackList	保留邮箱前缀列表	见 config.json

也可通过环境变量 PUBLIC_DIR 覆盖静态资源目录路径。

DNS 配置

要使邮箱服务正常接收邮件，需要为你的域名添加以下 DNS 记录：

类型	名称	内容	代理状态	备注
A	your-domain.com	你的服务器IP	可代理	主域名解析，可开启 CDN 代理
A	mail	你的服务器IP	仅 DNS	邮件子域名，不可开启代理
MX	your-domain.com	mail.your-domain.com	仅 DNS（优先级 10）	指定邮件服务器地址

注意事项：

• mail 子域名的 A 记录 必须设置为"仅 DNS"（不能开启 CDN 代理），否则 SMTP 端口 25 会被代理拦截，导致无法收信。
• MX 记录的优先级建议设为 10。
• 如果使用 Cloudflare 等 CDN 服务，主域名可以开启代理（橙色云朵），但 mail 子域名必须关闭代理（灰色云朵）。

项目结构

cmd/server/         程序入口
internal/
  config/           配置加载
  handler/          HTTP 路由与中间件
  hub/              WebSocket 连接管理与邮件路由
  smtpd/            SMTP 服务器与邮件解析
public/             前端静态文件
test/
  e2e/              端到端测试
  bench/            性能基准测试

测试

# 端到端测试（需先启动服务）
cd test/e2e && go run main.go

# 性能测试
cd test/bench && go run main.go all

许可证

GPL-2.0