API 文档

GPTMail API

使用 GPTMail API，可以通过 HTTPS 和 X-API-Key 请求头生成临时邮箱、列出和读取邮件以及删除邮件，适用于自动化测试、CI/CD 流水线和 QA 工作流。

如何获取 API Key

购买 API 额度

使用 GPTMail 积分购买 API 次数。签到、添加公共域名可获得积分，也可用 LDC 按 1:1 购买。

积分购买 / 追加额度

方式二：为本站添加你自己的域名

公共域名通过 MX 验证后：未登录时提交，赠送 API Key（20000 次请求）；登录后提交，赠送 200 积分。每个域名只能领取一种奖励。 请注意：该域名后缀接入后会成为本站公共可用后缀，其他用户同样可以在本站生成并使用这个后缀下的邮箱地址。接入成功后，不要删除、替换或修改该域名当前指向本站的 MX 记录，否则系统后续巡检时会判定配置失效；若后续检测到 MX 记录无效，该域名会被自动停用；若 MX 连续 3 次检测都无效，对应的 API Key 也会自动失效。若之后 MX 恢复有效，该域名会自动重新启用。

域名

公共测试 Key

测试时可在 X-API-Key 请求头中使用下方显示的公共 Key。它每天更换，所有用户共享每日 20万 次的请求额度。

今日剩余额度

重置倒计时

正在读取公共 Key 实时额度...

下方是 API 文档正文，可一键复制为 Markdown 提供给 AI、知识库或 README。

基础地址: https://mail.chatgpt.org.uk

AI
llms.txt

·

llms-full.txt

(Markdown)

快速开始

  • X-API-Key: YOUR_KEY 是最直接的方式；快速测试时，可用上方显示的每日公共 Key 替换 YOUR_KEY。

  • 大部分邮箱相关接口都需要传入 email 参数，例如 ?email=demo@example.com。

  • GPTMail API 响应采用 JSON，包含 success、data、error 字段，使用 API Key 时还会附带 usage。Cloudflare 错误（包括限速响应）可能返回 HTML，请先检查 HTTP 状态码和 Content-Type，再解析 JSON。

  • 如果你已经知道一个当前可用的本站域名，就不一定要先调用生成邮箱接口。你可以直接在本地拼出 前缀@域名，再用收件接口读取邮件，这样能省掉一次 API 调用。

调用限速与重试

  • GET 和 POST /api/generate-email 共用按来源 IP 计算的限速：每 10 秒最多 30 次。公共 Key 和个人 Key 均适用；同一 IP 下的不同 Key、不同客户端共用这一限制。

  • 超过限制会返回 HTTP 429，并拦截生成邮箱请求 10 秒。请按照 Retry-After 指定的时间等待后重试；若没有该响应头，至少等待 10 秒，再逐步延长重试间隔。同一 IP 下的客户端应避免同时重试。

  • 这条规则不适用于收件箱列表和单封邮件读取。API Key 的每日额度、总额度仍独立生效；Key 额度耗尽时，等待 10 秒不会恢复额度。

核心接口

POST / GET
/api/generate-email

生成一个临时邮箱。GET 可直接随机生成；POST 时可传 prefix 和 domain 指定前缀或域名。

GET
/api/emails?email=...

拉取某个邮箱下的邮件列表。

GET
/api/email/{id}?email=...

读取单封邮件详情，包括文本、HTML、原始头部等。

DELETE
/api/email/{id}?email=...

删除一封邮件。

DELETE
/api/emails/clear?email=...

清空指定邮箱的全部邮件。

GET
/api/stats

获取站点级统计信息。

调用示例

下面给出两种常见方式：一种是让服务端随机生成邮箱，另一种是指定固定前缀。如果你已经知道一个当前可用域名，也可以在本地直接拼接邮箱地址后调用收件接口。

1) 随机生成一个临时邮箱地址

curl 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'X-API-Key: PUBLIC_API_KEY'
返回示例
{
  "success": true,
  "data": {
    "email": "a3f9c2b1@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

2) 指定前缀生成邮箱（例如 demo@example.com）

curl -X POST 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: PUBLIC_API_KEY' \
  -d '{"prefix":"demo"}'
返回示例
{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 2,
    "remaining_today": 199998
  }
}

3) 查询收件箱 — 获取该邮箱的邮件列表

如果你已知当前可用域名，可跳过第 1 步直接拼地址查询。

curl 'https://mail.chatgpt.org.uk/api/emails?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
返回示例
{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "e5a7f3...",
        "email_address": "demo@example.com",
        "from_address": "noreply@github.com",
        "subject": "Your code: 654321",
        "content": "Your verification code is 654321",
        "html_content": "...",
        "has_html": true,
        "timestamp": 1709654321,
        "created_at": "2024-03-05T12:18:41Z"
      }
    ],
    "count": 1
  }
}

4) 读取单封邮件详情 — 包含纯文本、HTML 正文和元数据

将 EMAIL_ID 替换为第 3 步返回的邮件 id，并用 email 参数传入该邮箱地址（删除邮件、下载附件时同样适用）：服务端会直接从该邮箱读取邮件，无需按 id 搜索。 使用 API Key 时 email 参数可省略，但传入它可以让查询更快。

curl 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
返回示例
{
  "success": true,
  "data": {
    "id": "e5a7f3...",
    "email_address": "demo@example.com",
    "from_address": "noreply@github.com",
    "subject": "Your code: 654321",
    "content": "Your verification code is 654321",
    "html_content": "<p>Your code is 654321</p>",
    "has_html": true,
    "timestamp": 1709654321,
    "raw_size": 2048,
    "created_at": "2024-03-05T12:18:41Z"
  }
}

5) 删除单封邮件

使用 API Key 时 email 参数可省略，但传入它可以让查询更快。

curl -X DELETE 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
返回示例
{
  "success": true,
  "data": {
    "message": "Email deleted"
  }
}

6) 清空收件箱 — 删除该邮箱下所有邮件

每次调用删除一批邮件。只要响应中 "has_more" 为 true，就再次调用，直到它返回 false。

curl -X DELETE 'https://mail.chatgpt.org.uk/api/emails/clear?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
返回示例
{
  "success": true,
  "data": {
    "message": "Deleted 3 emails",
    "count": 3,
    "has_more": false
  }
}

响应格式

成功响应通常是下面这种结构；如果使用 API Key，请特别关注 usage 里的额度信息。

{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

扩展统计接口

  • /api/statistics/24h 返回一个 24 小时的每小时分布窗口；可用 offset=1、2、... 查看更早窗口。
  • /api/statistics/top-subjects 返回热门主题。
  • /api/statistics/top-domains 返回活跃域名排行。
  • /api/statistics/top-senders 返回热门发件人排行。
GPTMail