TempHotmail · API v1

邮箱 API 文档

在 Codex、Claude Code 或终端中创建测试邮箱并验证邮件投递。适用于有效的 Pro 月付和年付订阅。

连接 AI 工具

Codex App

  1. 在 App 的插件页面点「+」,选择「添加自定义 MCP」。也可以在设置的 MCP servers 中选择 Add server。
  2. 名称填写 TempHotmail,服务器地址填下方 URL。如果表单询问认证方式,选 OAuth,客户端注册选择 DCR。桌面设置里选择 Streamable HTTP。
  3. 保存后选择连接或认证。登录 TempHotmail,点击「授权并返回」。在新对话里选用 TempHotmail,或用 /mcp 检查连接。
https://temphotmail.com/mcp

每个连接只能访问自己创建的测试邮箱。可以在仪表盘的「API 密钥和应用连接」里单独撤销。

Codex CLI 密钥配置

把「AI 和 CLI 密钥」设为环境变量 TEMPHOTMAIL_API_KEY,然后把这段配置加入 ~/.codex/config.toml。

[mcp_servers.temphotmail]
url = "https://temphotmail.com/mcp"
bearer_token_env_var = "TEMPHOTMAIL_API_KEY"
tool_timeout_sec = 30

Claude Code

把「AI 和 CLI 密钥」设为环境变量 TEMPHOTMAIL_API_KEY。在项目根目录加入 .mcp.json,或把 temphotmail 合并进现有的 mcpServers。重启后用 /mcp 检查连接。

{
  "mcpServers": {
    "temphotmail": {
      "type": "http",
      "url": "https://temphotmail.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TEMPHOTMAIL_API_KEY}"
      }
    }
  }
}

试一次收件测试

帮我创建一个测试邮箱并告诉我地址。等我发送主题为 Welcome 的测试邮件后,帮我确认邮件是否收到。

工具包括 create_mailbox、list_mailboxes、list_messages、read_message 和 wait_for_email。等待最多 20 秒,按发件人或主题精确匹配。只有 read_message 返回正文。

在终端和 CI 中使用

CLI 需要 Node.js 22 或更高版本。使用同一个 TEMPHOTMAIL_API_KEY 环境变量。下方是 macOS 和 Linux 的安装命令,Windows 可下载文件后用 node temphotmail.mjs 运行。

下载 CLI
mkdir -p "$HOME/.local/bin"
curl -fsSL https://temphotmail.com/downloads/temphotmail.mjs \
  -o "$HOME/.local/bin/temphotmail"
chmod +x "$HOME/.local/bin/temphotmail"
"$HOME/.local/bin/temphotmail" --version
export PATH="$HOME/.local/bin:$PATH"
temphotmail mailbox create --idempotency-key signup-test-001 --json
# Send your test email to data.email, then replace MAILBOX_ID.
temphotmail mail wait --mailbox MAILBOX_ID --subject "Welcome" --timeout 20 --json

使用 temphotmail --help 查看所有命令。--json 将结果写到标准输出。等待超时返回退出码 3,方便 CI 区分超时和请求失败。

REST API 快速开始

REST 支持两种密钥。AI 和 CLI 密钥只访问自己创建的邮箱,账户 API 密钥可以访问账户下的所有 Premium 邮箱。将选用的密钥保存为 TEMPHOTMAIL_API_KEY。

curl -X POST https://temphotmail.com/api/v1/mailboxes \
  -H "Authorization: Bearer $TEMPHOTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inbox-test-001" \
  -d '{}'

向响应中的 data.email 发送一封测试邮件。把 data.id 填入下方的 MAILBOX_ID,然后查询收件箱。

curl "https://temphotmail.com/api/v1/mailboxes/MAILBOX_ID/messages?limit=25" \
  -H "Authorization: Bearer $TEMPHOTMAIL_API_KEY"

从列表中取出邮件 ID,替换 MESSAGE_ID 读取正文。邮件里的 HTML 来自发件人,渲染前请清理。

curl "https://temphotmail.com/api/v1/mailboxes/MAILBOX_ID/messages/MESSAGE_ID" \
  -H "Authorization: Bearer $TEMPHOTMAIL_API_KEY"

接口参考

基础地址 https://temphotmail.com/api/v1

  • POST /mailboxes

    创建邮箱。请求体可包含 name 和 domain,传入 {} 生成随机地址。

  • GET /mailboxes

    列出当前密钥有权访问且尚未到期的 Premium 邮箱。

  • GET /mailboxes/{mailboxId}/messages

    按收件时间从新到旧列出邮件。limit 默认为 25,最多 50。使用 next_cursor 读取下一页,返回 null 表示已经读完。

  • GET /mailboxes/{mailboxId}/messages/wait

    使用 AI 和 CLI 密钥等待邮件。可指定 subject、from、after 和 timeout_seconds。

  • GET /mailboxes/{mailboxId}/messages/{messageId}

    获取一封邮件的正文,包括 text_body 和 html_body。

配额和订阅到期

  • 每账户最多 25 个活跃邮箱,API 密钥和 OAuth 连接共用 5 个名额。创建限额为每 10 分钟 10 次,与网页共用。API 读取合计每分钟 120 次。
  • 24 小时内用相同的 Idempotency-Key 和参数重试创建,会返回原结果和 200。账户密钥按账户识别重试,AI 和 CLI 密钥各自独立。首次创建返回 201,参数冲突返回 409。
  • 取消自动续费后,API 可使用到已付周期结束。邮箱可用时间以响应中的 expires_at 为准。

错误处理

错误响应包含 error.code、error.message 和 request_id。联系支持时可提供 request_id。

400 / 413
参数无效或请求体过大。
401 · INVALID_API_KEY
密钥缺失、无效或已撤销。
403 · SUBSCRIPTION_REQUIRED
账户没有有效的 Pro 订阅。
403 · AUTOMATION_KEY_REQUIRED
此接口需要 AI 和 CLI 密钥。
404 · MAILBOX_NOT_FOUND / MESSAGE_NOT_FOUND
邮箱已过期或请求的资源不可访问。
409 · ADDRESS_CONFLICT / MAILBOX_LIMIT / IDEMPOTENCY_CONFLICT
邮箱地址冲突、达到邮箱额度或幂等键冲突。
429 · RATE_LIMITED
请求过多,按 Retry-After 指定的秒数等待后重试。
500 / 503
服务暂时无法完成请求。创建请求重试时请复用原幂等键。