GPTMail 公开 API 文档

📖 概述

GPTMail 提供了一套完整的 RESTful API 接口，允许开发者通过编程方式访问临时邮箱服务。所有 API 接口均采用 JSON 格式进行数据交换，支持跨域请求（CORS）。

基础 URL: https://mail.chatgpt.org.uk

API 版本: v1

---

🔐 认证方式

API Key 认证

所有 API 接口（除 /api/statistics/24h 外）都需要通过 API Key 进行认证。

测试 API Key

为了方便测试，我们提供了一个测试用的 API Key：

注意：测试 Key 仅用于开发和测试，生产环境请使用正式 API Key。

API Key 申请方式

正式 API Key 可通过以下方式申请：

使用方式

在 HTTP 请求头中添加 X-API-Key：

X-API-Key: gpt-test

示例：使用测试 Key gpt-test 进行调用

响应头说明

每次 API 调用都会在响应头中包含以下信息：

• X-RateLimit-Limit: 每日限制次数
• X-RateLimit-Remaining: 今日剩余次数
• X-RateLimit-Reset: 重置时间（Unix 时间戳）

超限处理

当达到每日调用限制时，API 会返回 HTTP 429 状态码：

{
  "error": "API调用失败: 已达到每日限制(1000次)",
  "remaining": 0,
  "reset_time": "2025-11-14 00:00:00"
}

---

📋 API 端点列表

1. 生成邮箱地址

生成一个新的临时邮箱地址（随机或自定义前缀）。

请求方式

方式一：随机生成（GET）

GET https://mail.chatgpt.org.uk/api/generate-email
Headers:
  X-API-Key: gpt-test

方式二：自定义前缀（POST）

POST https://mail.chatgpt.org.uk/api/generate-email
Headers:
  Content-Type: application/json
  X-API-Key: gpt-test
Body:
{
  "prefix": "myname",
  "domain": "gravityengine.cc"
}

请求参数

参数	类型	必填	说明
prefix	string	否	邮箱前缀（1-32字符，只能包含字母、数字、点、下划线和短横线）
domain	string	否	指定域名（如果未指定或域名不可用，将随机选择）

响应示例

200 成功响应：

{
  "email": "myname@gravityengine.cc"
}

400 错误响应：

{
  "error": "前缀格式不正确，只能包含字母、数字、点、下划线和短横线，长度1-32字符"
}

---

2. 获取邮件列表

获取指定邮箱地址的所有邮件。

请求示例

GET https://mail.chatgpt.org.uk/api/emails?email=test@gravityengine.cc
Headers:
  X-API-Key: gpt-test

请求参数

参数	类型	必填	说明
email	string	是	邮箱地址

响应示例

200 成功响应：

{
  "emails": [
    {
      "id": "1234567890",
      "from_address": "sender@example.com",
      "subject": "测试邮件",
      "preview": "这是一封测试邮件...",
      "created_at": "2025-11-14 10:30:00",
      "timestamp": 1699968600,
      "has_html": false
    }
  ],
  "count": 1
}

400 错误响应：

{
  "error": "请提供邮箱地址"
}

---

3. 获取单封邮件详情

获取指定邮件 ID 的完整内容。

请求示例

GET https://mail.chatgpt.org.uk/api/email/1234567890
Headers:
  X-API-Key: gpt-test

URL 参数

参数	类型	必填	说明
email_id	string	是	邮件 ID

响应示例

200 成功响应：

{
  "id": "1234567890",
  "email_address": "test@gravityengine.cc",
  "from_address": "sender@example.com",
  "subject": "测试邮件",
  "content": "这是一封测试邮件的完整内容...",
  "created_at": "2025-11-14 10:30:00",
  "timestamp": 1699968600,
  "has_html": false,
  "is_welcome": false
}

404 错误响应：

{
  "error": "邮件不存在"
}

---

4. 删除单封邮件

删除指定邮件 ID 的邮件。

请求示例

DELETE https://mail.chatgpt.org.uk/api/email/1234567890
Headers:
  X-API-Key: gpt-test

URL 参数

参数	类型	必填	说明
email_id	string	是	邮件 ID

响应示例

200 成功响应：

{
  "success": true,
  "message": "邮件已删除"
}

404 错误响应：

{
  "error": "邮件不存在"
}

---

5. 清空收件箱

删除指定邮箱地址的所有邮件。

请求示例

DELETE https://mail.chatgpt.org.uk/api/emails/clear?email=test@gravityengine.cc
Headers:
  X-API-Key: gpt-test

请求参数

参数	类型	必填	说明
email	string	是	邮箱地址

响应示例

200 成功响应：

{
  "success": true,
  "message": "已删除 5 封邮件"
}

400 错误响应：

{
  "error": "请提供邮箱地址"
}

---

6. 获取统计信息

获取系统统计信息（总邮件数、24小时邮件数、域名数量等）。

请求示例

GET https://mail.chatgpt.org.uk/api/stats
Headers:
  X-API-Key: gpt-test

响应示例

200 成功响应：

{
  "total_emails": 12345,
  "total_domains": 460,
  "emails_24h": 234,
  "domain_count": 460
}

---

7. 获取24小时统计数据（公开接口）

获取最近24小时的邮件统计数据，包括热门主题、热门域名、热门发件人等。

请求示例

GET https://mail.chatgpt.org.uk/api/statistics/24h

响应示例

200 成功响应：

{
  "success": true,
  "data": {
    "total_count": 1234,
    "hourly_distribution": [10, 15, 20, ...],
    "total_subjects": 567,
    "top_subjects": [
      {"subject": "验证码", "count": 45},
      {"subject": "欢迎", "count": 32}
    ],
    "total_domains": 89,
    "top_domains": [
      {"domain": "e*****e.com", "count": 123}
    ],
    "top_senders": [
      {"sender": "n*****y@e*****e.com", "count": 56}
    ],
    "site_domains_count": 460
  }
}

---

⚠️ 错误处理

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
401	未提供 API Key
403	API Key 无效或来源域名未授权
404	资源不存在
429	达到每日调用限制
500	服务器内部错误

错误响应格式

所有错误响应都采用统一的 JSON 格式：

{
  "error": "错误描述信息"
}

常见错误

1. 未提供 API Key

{
  "error": "API调用失败: 未提供API Key"
}

2. API Key 无效

{
  "error": "API调用失败: API Key无效"
}

3. 来源域名未授权

{
  "error": "API调用失败: 来源域名未授权"
}

4. 达到每日限制

{
  "error": "API调用失败: 已达到每日限制(1000次)",
  "remaining": 0,
  "reset_time": "2025-11-14 00:00:00"
}

---

📊 使用限制

每日调用限制

每个 API Key 都有独立的每日调用次数限制：

• 默认限制: 根据管理员配置
• 无限制: 设置为 0 表示无限制
• 重置时间: 每天 00:00:00 UTC

请求频率限制

• 建议频率: 每秒不超过 10 次请求
• 超频处理: 可能被临时限制访问

数据限制

• 邮件保留时间: 24 小时（自动删除）
• 邮箱前缀长度: 1-32 字符
• 单次查询邮件数: 最多 50 封

---

📞 支持与反馈

如有问题或建议，请通过以下方式联系：

• 网站: https://chatgpt.org.uk
• 邮箱服务: https://mail.chatgpt.org.uk

---

📝 更新日志

v1.0.0 (2025-11-14)

• ✅ 初始版本发布
• ✅ 支持邮箱生成、邮件查询、删除等功能
• ✅ API Key 认证机制
• ✅ 每日调用次数限制
• ✅ 24小时统计数据接口（公开）
• ✅ 域名和发件人邮箱脱敏处理

---

⚖️ 使用条款

1. 合理使用: 请合理使用 API，避免滥用
2. 数据隐私: 所有邮件数据在24小时后自动删除
3. 服务可用性: 不保证100%可用性，请做好错误处理
4. 禁止用途: 禁止用于垃圾邮件、恶意攻击等非法用途

最后更新: 2025年11月14日