AI导哈

临时邮箱API

一个自托管的临时邮箱REST API，内置Web UI和可选MCP服务器，聚合多个一次性邮箱提供商。

  • by Vozec
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Vozec/Tempmail-MCP

使用说明

Tempmail MCP

一个自托管的临时电子邮件REST API，带有内置的web UI和可选的MCP服务器。 多个一次性盒内提供程序聚合在一个API后面；启动时会自动检测并禁用损坏的提供程序。

特性

  • 多供应商 --mail.tm、tempmail.io、Gmail（IMAP）、邮件收发、tempmailo、tempail
  • 自动回退 --按优先级顺序选择第一个健康的提供者
  • 断路器 --连续3次失败的提供商将自动禁用；通过API重新启用
  • 启动健康检查 --在第一个请求之前禁用损坏的提供程序
  • 网页用户界面 --基于标签的电子邮件客户端、多帐户、本地存储持久性、自动刷新、浏览器通知
  • 共享/固定电子邮件 --pin邮箱服务器端，这样每个客户端都可以使用它们
  • Swagger文档 — /docs
  • MCP服务器 --可选，可由Claude/任何MCP客户端独立使用
  • Cloudflare旁路 --via FlareSolverr 对于需要它的提供商

快速入门（Docker Compose）

cp .env.example .env
# edit .env if needed (Gmail credentials, ports, …)
docker compose up -d
  • 网页用户界面→ http://localhost:8000
  • 昂首阔步→ http://localhost:8000/docs

配置(.env)

变量 默认值 描述
HOST 0.0.0.0 绑定地址
PORT 8000 HTTP端口
RELOAD false Uvicorn热重载（仅限开发人员）
ENABLE_FRONTEND true 提供web UI
FLARESOLVERR_URL http://localhost:8191 FlareSolverr端点
HEALTH_CHECK_ON_STARTUP true 在启动时探测所有提供程序并禁用故障
SHARED_EMAILS_PATH shared_emails.json 服务器端固定电子邮件存储的路径
GMAIL_EMAIL -- Gmail地址（适用于Gmail IMAP提供商）
GMAIL_APP_PASSWORD -- Gmail应用程序密码

REST API

系统

方法 路径 描述
GET /api/health 所有提供者的健康状况（如果一切正常，则为200，如果降级，则为207）

回应 GET /api/health

{
  "healthy": true,
  "providers": {
    "mail.tm":    { "status": "ok" },
    "mailticking": { "status": "disabled", "failures": 3 }
  }
}

提供商

方法 路径 描述
GET /api/providers 列出所有处于启用/失败状态的提供程序
POST /api/providers/{name}/disable 手动禁用提供程序
POST /api/providers/{name}/enable 重新启用提供程序并重置故障计数器
GET /api/domains?name=<provider> 列出提供程序的可用域

回应 GET /api/providers

[
  { "name": "gmail",      "disabled": false, "failures": 0 },
  { "name": "mail.tm",    "disabled": false, "failures": 0 },
  { "name": "mailticking","disabled": true,  "failures": 3 }
]

电子邮件

name 在每个端点上都是可选的——省略表示“自动”（优先级顺序中的第一个健康提供者）。

方法 路径 描述
POST /api/email?name=<provider> 创建新的临时邮箱
GET /api/email/{email}/messages?token=X&name=Y 列出邮箱的邮件
GET /api/email/{email}/message/{id}?token=X&name=Y 获取完整消息（带正文）
DELETE /api/email/{email}?token=X&name=Y 删除邮箱

请求 POST /api/email

{
  "min_name_length": 10,
  "max_name_length": 10,
  "domain": null
}

回应 POST /api/email

{
  "email": "randomname@mail.tm",
  "token": "eyJ...",
  "provider": "mail.tm"
}

回应 GET /api/email/{email}/messages

[
  {
    "id": "abc123",
    "from_addr": "\"Alice\" <alice@example.com>",
    "to_addr": "randomname@mail.tm",
    "subject": "Your verification code",
    "body_text": null,
    "body_html": null,
    "created_at": "1742900000",
    "attachments": []
  }
]

回应 GET /api/email/{email}/message/{id}

{
  "id": "abc123",
  "from_addr": "\"Alice\" <alice@example.com>",
  "to_addr": "randomname@mail.tm",
  "subject": "Your verification code",
  "body_text": "Your code is 123456",
  "body_html": "<html>...</html>",
  "created_at": "1742900000",
  "attachments": [
    { "filename": "invoice.pdf", "content_type": "application/pdf", "size": 42300, "url": null }
  ]
}

共享/固定电子邮件

在服务器端固定一个邮箱，这样每个客户端都可以看到并重用它。

方法 路径 描述
GET /api/shared 列出所有固定电子邮件帐户
POST /api/shared 固定电子邮件（对所有客户端可见）
PATCH /api/shared/{email} 重命名固定电子邮件（更新标签）
DELETE /api/shared/{email} 不愉快的电子邮件

请求 POST /api/shared

{
  "email": "randomname@mail.tm",
  "token": "eyJ...",
  "provider": "mail.tm",
  "label": "My shared inbox"
}

回应 GET /api/shared

[
  {
    "email": "randomname@mail.tm",
    "token": "eyJ...",
    "provider": "mail.tm",
    "label": "My shared inbox",
    "pinned_at": 1742900000
  }
]

提供商

优先顺序（第一个健康提供者获胜）：

优先级 名称 类型 需要FlareSolverr 备注
1 gmail IMAP 否 需要 GMAIL_EMAIL + GMAIL_APP_PASSWORD
2 mail.tm REST API 否 最可靠的回退
3 tempmail.io REST API 否 可靠
4 mailticking 刮擦 是 CF保护
5 tempmailo 刮擦 是 CF保护
6 tempail 刮擦 是 可能被reCAPTCHA阻止

在启动时，每个提供者都会被一个真实的 create_email 电话。任何失败的提供程序在处理请求之前都会自动禁用。

MCP服务器

MCP服务器在以下位置自动暴露 /mcp/ 当FastAPI应用程序运行时，不需要单独的进程。

HTTP传输（推荐）

添加到MCP配置(~/.mcp.json 对于克劳德代码， ~/.config/claude/claude_desktop_config.json 克劳德桌面版）：

{
  "mcpServers": {
    "tempmail": {
      "type": "http",
      "url": "https://your-host/mcp/"
    }
  }
}

注： 尾随斜线 /mcp/ 是必需的。

独立标准输入模式

python -m src.mcp_server

{
  "mcpServers": {
    "tempmail": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/tempmail-api"
    }
  }
}

可用工具

工具 说明
list_providers 列出所有具有状态的提供商(disabled, failures)
disable_provider 手动禁用提供程序
enable_provider 重新启用提供程序并重置故障计数器
get_domains 列出提供程序的可用域
create_email 创建新的一次性邮箱
get_messages 在收件箱中轮询新邮件
read_message 阅读邮件的全文
delete_email 销毁邮箱
list_pinned 列出所有共享/固定电子邮件
pin_email 固定邮箱，以便所有客户端都可以重复使用
unpin_email 删除固定电子邮件
rename_email 更新固定电子邮件的显示标签

发展

pip install -r src/requirements.txt
RELOAD=true python -m src.main

FlareSolverr（CF保护提供商需要）：

docker run -p 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest

相关 MCP