mail-curl

一个轻量级临时邮箱聚合服务。项目把多个临时邮箱 Provider 封装成统一的 HTTP API，方便用 curl 或其他客户端创建邮箱、轮询收件箱、读取邮件内容。

功能

• 统一的邮箱 API：创建邮箱、查询收件箱、读取邮件详情
• 支持多个 Provider，并可通过 /all 随机选择可用 Provider
• 通过 key 查询参数做简单访问控制
• 支持 .env 和 .env.local 配置
• 可直接用 Node.js 运行，也提供 Dockerfile

环境要求

• Node.js 18 或更高版本
• npm

支持的 Provider

Provider	说明	默认状态
chatgpt_mail	通过 HTTP API 接入 ChatGPT Mail	设置 CHATGPT_MAIL_API_KEY 后启用
twenty_four_email	通过 24.email 生成邮箱，使用 WebSocket 读取收件箱并解析 HTML	启用
generator_email	通过 generator.email 生成邮箱并解析 HTML 收件箱和邮件详情	启用
temp_mail_io	通过 temp-mail.io JSON 接口生成邮箱并读取消息	启用
tempmailo	通过 tempmailo.com Web 流程生成邮箱并读取消息	启用
guerrilla_mail	通过 Guerrilla Mail JSON/Cookie API 创建邮箱并读取消息	启用
mail_tm	通过 mail.tm JSON/Bearer 接口创建邮箱并读取消息	启用
priyo_email	通过 priyo.email Web/Livewire 流程切换邮箱并解析消息	启用

除 chatgpt_mail 外，Provider 默认启用。将对应的 *_ENABLED 设置为 0、false、no 或 off 可以关闭。

安装

npm install

配置

服务会按顺序读取项目根目录下的 .env 和 .env.local。已存在于系统环境变量中的值优先级更高。

最小配置示例：

MC_KEY=your-secret-key
PORT=3100
HOST=0.0.0.0

可用环境变量：

变量	默认值	说明
PORT	3100	HTTP 服务端口
HOST	::	HTTP 监听地址
MC_KEY	sk-test	API 访问密钥，请求时通过 key 参数传入
CHATGPT_MAIL_API_KEY	空	存在时启用 chatgpt_mail
CHATGPT_MAIL_ENABLED	启用	设置为 0、false、no 或 off 可关闭
CHATGPT_MAIL_BASE_URL	https://mail.chatgpt.org.uk	chatgpt_mail 上游地址
CHATGPT_MAIL_TIMEOUT_MS	10000	请求超时时间
TWENTY_FOUR_EMAIL_ENABLED	启用	是否启用 twenty_four_email
TWENTY_FOUR_EMAIL_BASE_URL	https://24.email	twenty_four_email 上游地址
TWENTY_FOUR_EMAIL_TIMEOUT_MS	10000	请求超时时间
GENERATOR_EMAIL_ENABLED	启用	是否启用 generator_email
GENERATOR_EMAIL_BASE_URL	https://generator.email	generator_email 上游地址
GENERATOR_EMAIL_TIMEOUT_MS	10000	请求超时时间
TEMP_MAIL_IO_ENABLED	启用	是否启用 temp_mail_io
TEMP_MAIL_IO_BASE_URL	https://api.internal.temp-mail.io	temp_mail_io API 地址
TEMP_MAIL_IO_SITE_URL	https://temp-mail.io	temp_mail_io 站点地址
TEMP_MAIL_IO_CORS_HEADER	1	上游请求头 X-CORS-Header
TEMP_MAIL_IO_TIMEOUT_MS	10000	请求超时时间
TEMPMAILO_ENABLED	启用	是否启用 tempmailo
TEMPMAILO_BASE_URL	https://tempmailo.com	tempmailo 上游地址
TEMPMAILO_SITE_URL	https://tempmailo.com	tempmailo 站点地址
TEMPMAILO_TIMEOUT_MS	10000	请求超时时间
GUERRILLA_MAIL_ENABLED	启用	是否启用 guerrilla_mail
GUERRILLA_MAIL_BASE_URL	https://api.guerrillamail.com/ajax.php	guerrilla_mail API 地址
GUERRILLA_MAIL_TIMEOUT_MS	10000	请求超时时间
MAIL_TM_ENABLED	启用	是否启用 mail_tm
MAIL_TM_BASE_URL	https://api.mail.tm	mail_tm API 地址
MAIL_TM_SITE_URL	https://mail.tm	mail_tm 站点地址
MAIL_TM_PASSWORD	空	固定邮箱密码；为空时为每个邮箱生成随机密码并写入 mailbox id
MAIL_TM_TIMEOUT_MS	10000	请求超时时间
PRIYO_EMAIL_ENABLED	启用	是否启用 priyo_email
PRIYO_EMAIL_BASE_URL	https://priyo.email	priyo_email 上游地址
PRIYO_EMAIL_TIMEOUT_MS	20000	请求超时时间

启动

npm start

默认地址：

http://localhost:3100

API

所有业务接口都需要传入 key 查询参数：

?key=<MC_KEY>

Provider 名称：

• all
• chatgpt_mail
• twenty_four_email
• generator_email
• temp_mail_io
• tempmailo
• guerrilla_mail
• mail_tm
• priyo_email

all 会在支持目标能力的已启用 Provider 中随机选择一个。使用 all 创建邮箱时，返回的 id 会带 Provider 前缀；后续查询收件箱和邮件详情必须继续传这个带前缀的 id。

健康检查

curl http://localhost:3100/health

响应示例：

{
  "ok": true,
  "providers": [
    {
      "name": "temp_mail_io",
      "capabilities": {
        "createMailbox": true,
        "listInbox": true,
        "getMail": true,
        "transport": "json"
      }
    }
  ]
}

创建邮箱

curl -X POST "http://localhost:3100/all/api/remail?key=your-secret-key"

响应示例：

{
  "id": "temp_mail_io::user@example.com",
  "email": "user@example.com",
  "provider": "temp_mail_io",
  "provider_id": "user@example.com"
}

指定 Provider：

curl -X POST "http://localhost:3100/temp_mail_io/api/remail?key=your-secret-key"

查询收件箱

curl "http://localhost:3100/all/api/inbox?key=your-secret-key&mailbox_id=temp_mail_io::user@example.com"

响应示例：

[
  {
    "mail_id": "temp_mail_io::user@example.com::message-id",
    "sender_name": "openai sender@example.com",
    "subject": "Verify your email",
    "received_at": "2026-05-21T10:00:00.000Z",
    "provider": "temp_mail_io",
    "provider_mail_id": "user@example.com::message-id"
  }
]

指定 Provider 时，mailbox_id 使用创建邮箱接口返回的原始 id：

curl "http://localhost:3100/temp_mail_io/api/inbox?key=your-secret-key&mailbox_id=user@example.com"

读取邮件

curl "http://localhost:3100/all/api/mail?key=your-secret-key&id=temp_mail_io::user@example.com::message-id"

响应示例：

{
  "id": "temp_mail_io::user@example.com::message-id",
  "subject": "Verify your email",
  "content": "Your verification code is 123456",
  "html": "<p>Your verification code is 123456</p>",
  "from": "sender@example.com",
  "received_at": "2026-05-21T10:00:00.000Z",
  "provider": "temp_mail_io",
  "provider_mail_id": "user@example.com::message-id"
}

指定 Provider：

curl "http://localhost:3100/temp_mail_io/api/mail?key=your-secret-key&id=user@example.com::message-id"

错误响应

错误统一返回 JSON：

{
  "error": "bad_request",
  "message": "mailbox_id is required"
}

常见状态码：

状态码	说明
400	参数错误或 Provider 不可用
401	key 不正确
404	路由不存在
405	HTTP 方法不允许
502	上游 Provider 请求失败
500	服务内部错误

Docker

构建镜像：

docker build -t mail-curl .

运行：

docker run --rm -p 3100:3100 --env-file .env mail-curl

推送镜像：

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t lff0/mail-curl:latest \
  --push \
  .

注意：当前 Dockerfile 使用 npm ci，构建镜像前需要存在 package-lock.json。如果项目没有 lockfile，请先执行 npm install 生成。

开发说明

项目结构：

index.js                         # 服务入口
src/server.js                    # 路由、鉴权、Provider 注册
src/config.js                    # 环境变量配置
src/errors.js                    # 统一错误模型
src/http-client.js               # fetch 封装
src/providers/                   # Provider 实现

新增 Provider 时通常需要：

1. 在 src/providers/ 下新增 Provider 实现。
2. 在 src/config.js 增加配置和启用逻辑。
3. 在 src/server.js 的 createProviders() 中注册 Provider。
4. 实现统一接口：

{
  name: "provider_name",
  capabilities() {},
  async createMailbox() {},
  async listInbox({ mailboxId }) {},
  async getMail({ id }) {}
}

当前 package.json 只提供 start 脚本，暂未配置测试、lint 或构建脚本。