GPTMail已开放API，附API文档

AIblog

15 Nov, 2025

GPTMail 公开 API 文档 / GPTMail Public API Documentation

GPTMail 公开 API 文档

📖 概述

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

基础 URL（示例）：https://mail.chatgpt.org.uk

API 版本：v1

🔐 鉴权与通用规则

鉴权方式

除特别说明外，所有接口均需携带有效 API Key：

请求头方式：X-API-Key: <your-key>
或 URL 查询参数：?api_key=<your-key>

测试 API Key

为了方便测试，我们提供了一个测试用的 API Key（仅用于开发调试）：

测试 Key：gpt-test
每日调用限制：视情况调整

注意：测试 Key 不能用于正式生产环境，请为线上环境申请独立的正式 Key。

API Key 申请方式

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

申请链接：Linux Do CDK 分发平台
每个 API Key 拥有独立的每日调用配额（目前默认约为 2000 次/天）。

统一响应格式

所有接口返回统一结构：

{
  "success": true,          // 或 false
  "data": {...},            // 成功时为具体数据，失败时为空或省略
  "error": ""               // 失败时为错误信息，成功时为空字符串
}

success = true：请求成功，data 中包含业务数据，error 为空字符串。
success = false：请求失败，data 为空或缺省，error 包含错误原因。

时间字段约定

timestamp：Unix 时间戳（秒）。
created_at：数据库返回的时间字符串（ISO 风格，例如 2025-11-14 10:30:00）。

📋 API 端点列表

1. 生成邮箱地址

生成一个新的临时邮箱地址，可随机生成，也可指定前缀和域名。

GET POST /api/generate-email 需要 API Key

请求参数

支持 GET（无请求体，完全随机）或 POST（带 JSON 体）：

POST https://mail.chatgpt.org.uk/api/generate-email
Headers:
  Content-Type: application/json
  X-API-Key: gpt-test

Body:
{
  "prefix": "myname",
  "domain": "example.com"
}

参数	类型	必填	说明
prefix	string	否	邮箱前缀，长度 1–32，允许字母、数字、点（.）、下划线（_）、短横线（-）。
domain	string	否	需已在系统中激活的域名；如未提供或域名未激活，将从可用域名中随机选择。

返回数据

data 字段示例：

{
  "success": true,
  "data": {
    "email": "myname@example.com"
  },
  "error": ""
}

curl 示例

curl -X GET "https://mail.chatgpt.org.uk/api/generate-email" \
  -H "X-API-Key: gpt-test"

2. 获取邮箱邮件列表

获取指定邮箱地址的最近邮件列表。

GET /api/emails 需要 API Key

请求参数

GET "https://mail.chatgpt.org.uk/api/emails?email=test@example.com" \
  -H "X-API-Key: gpt-test"

参数	类型	必填	说明
email	string	是	要查询的完整邮箱地址。

返回数据

data 字段结构：

{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "1234567890",
        "email_address": "test@example.com",
        "from_address": "sender@example.com",
        "subject": "测试邮件",
        "content": "纯文本内容（最多截断至 10k 字符）",
        "html_content": "<html>...（最多截断至 2MB）",
        "has_html": true,
        "timestamp": 1699968600,
        "created_at": "2025-11-14 10:30:00"
      }
    ],
    "count": 1
  },
  "error": ""
}

content：纯文本版本内容（截断到约 10k 字符）。
html_content：HTML 内容（截断到约 2MB）。
has_html：是否存在 HTML 内容。

3. 获取单封邮件详情

按邮件 ID 获取完整邮件内容及原始数据。

GET /api/email/{id} 需要 API Key

请求示例

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

URL 参数

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

返回数据

data 为单个邮件对象，字段与列表接口相同，额外包含：

raw_content：原始邮件内容（RAW，截断约 100k 字符）。
headers：解析出的邮件头（若有）。
raw_size：原始邮件大小（字节）。

{
  "success": true,
  "data": {
    "id": "1234567890",
    "email_address": "test@example.com",
    "from_address": "sender@example.com",
    "subject": "测试邮件",
    "content": "纯文本内容...",
    "html_content": "<html>...",
    "has_html": true,
    "timestamp": 1699968600,
    "created_at": "2025-11-14 10:30:00",
    "raw_content": "RAW MIME 内容（截断）",
    "headers": {
      "Received": "...",
      "User-Agent": "..."
    },
    "raw_size": 12345
  },
  "error": ""
}

4. 删除单封邮件

按 ID 删除指定邮件。

DELETE /api/email/{id} 需要 API Key

请求示例

curl -X DELETE "https://mail.chatgpt.org.uk/api/email/1234567890" \
  -H "X-API-Key: gpt-test"

返回数据

{
  "success": true,
  "data": {
    "message": "Email deleted"
  },
  "error": ""
}

如果邮件不存在，将返回 success=false，同时 HTTP 状态码为 404。

5. 清空邮箱

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

DELETE /api/emails/clear 需要 API Key

请求示例

curl -X DELETE "https://mail.chatgpt.org.uk/api/emails/clear?email=test@example.com" \
  -H "X-API-Key: gpt-test"

返回数据

{
  "success": true,
  "data": {
    "message": "Deleted 5 emails",
    "count": 5
  },
  "error": ""
}

6. 基础统计 / 系统状态

获取系统级聚合统计数据。

GET /api/stats 需要 API Key

请求示例

curl "https://mail.chatgpt.org.uk/api/stats" \
  -H "X-API-Key: gpt-test"

返回数据

{
  "success": true,
  "data": {
    "total_emails": 12345,        // 系统累计邮件总数
    "today_emails": 456,          // 当天（按 UTC 日期）邮件数
    "emails_24h": 789,            // 过去 24 小时邮件数
    "unique_subjects": 567,       // 过去 24 小时唯一主题数量
    "active_domains": 120,        // 数据库中已激活域名数（可用于收件）
    "domain_count": 460           // 配置的全部域名数
  },
  "error": ""
}

7. 24 小时邮件分布

按小时返回最近 24 小时的邮件计数，用于绘制流量曲线。

GET /api/statistics/24h 需要 API Key

请求示例

curl "https://mail.chatgpt.org.uk/api/statistics/24h" \
  -H "X-API-Key: gpt-test"

返回数据

data 为数组，每个元素包含一个小时段的统计：

{
  "success": true,
  "data": [
    { "hour": "2025-11-14 10:00:00", "count": 10 },
    { "hour": "2025-11-14 11:00:00", "count": 25 }
  ],
  "error": ""
}

8. 热门主题（脱敏）

获取最近一段时间的热门邮件主题，主题内容已脱敏，仅用于趋势展示。

GET /api/statistics/top-subjects 需要 API Key

请求示例

curl "https://mail.chatgpt.org.uk/api/statistics/top-subjects" \
  -H "X-API-Key: gpt-test"

返回数据

{
  "success": true,
  "data": [
    { "subject": "验*****", "count": 45 },
    { "subject": "欢*****", "count": 32 }
  ],
  "error": ""
}

默认返回 Top 10，具体数量可根据后台配置调整。

9. 热门域名（按收件人域，脱敏）

统计最近一段时间内，收件人邮箱所使用的热门域名。

GET /api/statistics/top-domains 需要 API Key

请求示例

curl "https://mail.chatgpt.org.uk/api/statistics/top-domains" \
  -H "X-API-Key: gpt-test"

返回数据

{
  "success": true,
  "data": [
    { "domain": "ex****le.com", "count": 123 }
  ],
  "error": ""
}

域名采用脱敏显示，通常保留首尾字符，中间用 * 替代，避免暴露完整可用域名列表。

10. 热门发件人（脱敏）

统计最近一段时间内的热门发件人邮箱地址，包含本地部分和域名的脱敏显示。

GET /api/statistics/top-senders 需要 API Key

请求示例

curl "https://mail.chatgpt.org.uk/api/statistics/top-senders" \
  -H "X-API-Key: gpt-test"

返回数据

{
  "success": true,
  "data": [
    { "sender": "us***@ex***.com", "count": 56 }
  ],
  "error": ""
}

规则示例：user@example.com → us***@ex***.com。

11. 自助提交域名（验证 MX）

用户可自助提交希望接收邮件的域名，系统会验证其 MX 是否指向预期服务器。

POST /api/domains/request 需要 API Key

请求示例

curl -X POST "https://mail.chatgpt.org.uk/api/domains/request" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gpt-test" \
  -d '{"domain":"example.com"}'

请求体

字段	类型	必填	说明
domain	string	是	要提交验证的域名（需可正确解析 MX）。

返回数据

成功示例：

{
  "success": true,
  "data": {
    "domain": "example.com"
  },
  "error": ""
}

失败时 success=false，error 为错误原因（如格式错误、已存在、MX 未指向预期主机等）。

⚠️ 错误处理

HTTP 状态码

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

错误响应示例

1. 未带 Key（鉴权开启）

{
  "success": false,
  "data": null,
  "error": "API key required"
}

2. 配额超限

{
  "success": false,
  "data": null,
  "error": "Daily quota exceeded"
}

3. 无可用域名

{
  "success": false,
  "data": null,
  "error": "No active domains available"
}

4. 域名不受支持

{
  "success": false,
  "data": null,
  "error": "Unsupported domain"
}

📊 使用说明与限制

域名使用说明

/api/generate-email 与 /api/emails 使用的域名必须在系统中处于激活状态。
否则会返回 "No active domains available" 或类似“不支持的域名”错误。

统计接口说明

统计接口返回的热门主题、热门域名、热门发件人均已脱敏，仅用于趋势展示，不暴露真实业务数据。

配额与频率（建议值）

每个 Key 有独立每日调用配额，配额用完后会返回 429 与 "Daily quota exceeded"。
建议 QPS 不超过 10，避免被限流。

📞 支持与反馈

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

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

📝 更新日志

v1.0.0（2025-11-14）

✅ 初始版本发布。
✅ 支持邮箱生成、邮件查询、删除及清空收件箱。
✅ 统一响应格式：{success, data, error}。
✅ 新增基础统计 / 24 小时分布 / 热门主题 / 热门域名 / 热门发件人接口。
✅ 支持自助提交域名并验证 MX 记录。

⚖️ 使用条款

合理使用：请合理使用 API，避免恶意刷接口或绕过配额限制。
数据隐私：系统会在合理期限内清理邮件数据，统计接口仅以脱敏形式展示趋势。
服务可用性：不保证 100% 可用性，请在客户端做好重试与降级策略。
禁止用途：严禁用于发送垃圾邮件、钓鱼、攻击、违法或违规用途。

最后更新：2025-11-14

GPTMail Public API Documentation

📖 Overview

GPTMail provides a RESTful API that allows developers to access temporary email services programmatically. All endpoints use JSON for data exchange and support Cross-Origin Resource Sharing (CORS).

Base URL (example): https://mail.chatgpt.org.uk

API Version: v1

🔐 Authentication & General Rules

Authentication

Unless otherwise specified, all endpoints require a valid API key. You can provide it in either of the following ways:

Header: X-API-Key: <your-key>
Query string: ?api_key=<your-key>

Test API Key

For development and testing, a public test key is available:

Test Key: gpt-test
Daily Limit: ~2000 requests (actual quota is subject to server configuration)

Note: The test key is for non-production use only. Please apply for a dedicated key for production environments.

How to Get an API Key

You can obtain a production API key via:

Apply here: Linux Do CDK Distribution Platform
Each API key has its own daily quota (currently around 2000/day by default).

Unified Response Format

All endpoints use the same top-level response structure:

{
  "success": true,          // or false
  "data": {...},            // business payload when success = true
  "error": ""               // error message when success = false
}

When success = true, data contains the requested payload and error is an empty string.
When success = false, data is empty or omitted and error contains a human-readable error string.

Time Fields

timestamp: Unix timestamp in seconds.
created_at: ISO-like datetime string (as stored in the database, e.g. 2025-11-14 10:30:00).

📋 API Endpoints

1. Generate Email Address

Create a new temporary email address, either random or with a specified prefix / domain.

GET POST /api/generate-email API Key Required

Request

You can either:

Use GET with no body to generate a fully random address.
Use POST with JSON body to specify prefix and/or domain.

POST https://mail.chatgpt.org.uk/api/generate-email
Headers:
  Content-Type: application/json
  X-API-Key: gpt-test

Body:
{
  "prefix": "myname",
  "domain": "example.com"
}

Parameter	Type	Required	Description
prefix	string	No	Email prefix, length 1–32; allowed characters: letters, digits, dot (`.`), underscore (`_`), hyphen (`-`).
domain	string	No	Domain that must be activated in the system. If omitted or inactive, a random active domain is chosen.

Response

{
  "success": true,
  "data": {
    "email": "myname@example.com"
  },
  "error": ""
}

curl Example

curl -X GET "https://mail.chatgpt.org.uk/api/generate-email" \
  -H "X-API-Key: gpt-test"

2. List Emails for an Address

List recent emails received by a specific address.

GET /api/emails API Key Required

Request

curl "https://mail.chatgpt.org.uk/api/emails?email=test@example.com" \
  -H "X-API-Key: gpt-test"

Parameter	Type	Required	Description
email	string	Yes	The full email address to fetch messages for.

Response

data payload:

{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "1234567890",
        "email_address": "test@example.com",
        "from_address": "sender@example.com",
        "subject": "Test email",
        "content": "Plain text content (truncated to ~10k chars)",
        "html_content": "<html>... (truncated to ~2MB)",
        "has_html": true,
        "timestamp": 1699968600,
        "created_at": "2025-11-14 10:30:00"
      }
    ],
    "count": 1
  },
  "error": ""
}

content: Plain text body, truncated to about 10k characters.
html_content: HTML body, truncated to about 2MB.
has_html: Indicates whether HTML content is available.

3. Get Single Email Detail

Fetch the full content and raw data of a specific email by ID.

GET /api/email/{id} API Key Required

Request

curl "https://mail.chatgpt.org.uk/api/email/1234567890" \
  -H "X-API-Key: gpt-test"

Path Variable	Type	Required	Description
id	string	Yes	Email ID.

Response

The data object contains the same fields as the list endpoint, plus raw fields:

raw_content: Raw MIME content (truncated to ~100k characters).
headers: Parsed headers, if available.
raw_size: Raw message size in bytes.

{
  "success": true,
  "data": {
    "id": "1234567890",
    "email_address": "test@example.com",
    "from_address": "sender@example.com",
    "subject": "Test email",
    "content": "Plain text content...",
    "html_content": "<html>...",
    "has_html": true,
    "timestamp": 1699968600,
    "created_at": "2025-11-14 10:30:00",
    "raw_content": "Raw MIME content (truncated)",
    "headers": {
      "Received": "...",
      "User-Agent": "..."
    },
    "raw_size": 12345
  },
  "error": ""
}

If the email does not exist, the API returns success=false with HTTP 404.

4. Delete a Single Email

Delete a specific email by ID.

DELETE /api/email/{id} API Key Required

Request

curl -X DELETE "https://mail.chatgpt.org.uk/api/email/1234567890" \
  -H "X-API-Key: gpt-test"

Response

{
  "success": true,
  "data": {
    "message": "Email deleted"
  },
  "error": ""
}

If the email is not found, the API returns success=false with HTTP 404.

5. Clear Inbox

Delete all emails for a specified email address.

DELETE /api/emails/clear API Key Required

Request

curl -X DELETE "https://mail.chatgpt.org.uk/api/emails/clear?email=test@example.com" \
  -H "X-API-Key: gpt-test"

Response

{
  "success": true,
  "data": {
    "message": "Deleted 5 emails",
    "count": 5
  },
  "error": ""
}

6. Basic System Statistics

Retrieve system-wide aggregated statistics.

GET /api/stats API Key Required

Request

curl "https://mail.chatgpt.org.uk/api/stats" \
  -H "X-API-Key: gpt-test"

Response

{
  "success": true,
  "data": {
    "total_emails": 12345,       // Total number of emails ever processed
    "today_emails": 456,         // Emails received today (UTC date)
    "emails_24h": 789,           // Emails in the last 24 hours
    "unique_subjects": 567,      // Unique subjects in the last 24 hours
    "active_domains": 120,       // Number of domains currently activated for receiving
    "domain_count": 460          // Total configured domains
  },
  "error": ""
}

7. 24-Hour Distribution

Get hourly email counts for the last 24 hours to build traffic charts.

GET /api/statistics/24h API Key Required

Request

curl "https://mail.chatgpt.org.uk/api/statistics/24h" \
  -H "X-API-Key: gpt-test"

Response

data is an array; each entry represents one hour:

{
  "success": true,
  "data": [
    { "hour": "2025-11-14 10:00:00", "count": 10 },
    { "hour": "2025-11-14 11:00:00", "count": 25 }
  ],
  "error": ""
}

8. Top Subjects (Masked)

Return popular email subjects over a recent time window. Subjects are masked and are for trend visualization only.

GET /api/statistics/top-subjects API Key Required

Request

curl "https://mail.chatgpt.org.uk/api/statistics/top-subjects" \
  -H "X-API-Key: gpt-test"

Response

{
  "success": true,
  "data": [
    { "subject": "co***", "count": 45 },
    { "subject": "we***", "count": 32 }
  ],
  "error": ""
}

By default, the server returns the top 10 subjects (exact number may be configurable).

9. Top Recipient Domains (Masked)

Return popular recipient domains over a recent time window, masked to avoid exposing the full supported domain list.

GET /api/statistics/top-domains API Key Required

Request

curl "https://mail.chatgpt.org.uk/api/statistics/top-domains" \
  -H "X-API-Key: gpt-test"

Response

{
  "success": true,
  "data": [
    { "domain": "ex****le.com", "count": 123 }
  ],
  "error": ""
}

A typical masking strategy keeps the first and last characters and replaces the middle with asterisks.

10. Top Senders (Masked)

Return popular sender email addresses over a recent time window. Both local part and domain are masked.

GET /api/statistics/top-senders API Key Required

Request

curl "https://mail.chatgpt.org.uk/api/statistics/top-senders" \
  -H "X-API-Key: gpt-test"

Response

{
  "success": true,
  "data": [
    { "sender": "us***@ex***.com", "count": 56 }
  ],
  "error": ""
}

Example masking: user@example.com → us***@ex***.com.

11. Self-Service Domain Submission (MX Validation)

Allow users to submit domains they want to receive mail for. The system validates MX records to ensure they point to the expected host.

POST /api/domains/request API Key Required

Request

curl -X POST "https://mail.chatgpt.org.uk/api/domains/request" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gpt-test" \
  -d '{"domain":"example.com"}'

Field	Type	Required	Description
domain	string	Yes	The domain to request and validate (must have correct MX records).

Response

On success:

{
  "success": true,
  "data": {
    "domain": "example.com"
  },
  "error": ""
}

On failure, success=false and error explains the reason (invalid format, already exists, MX not pointing to the expected host, etc.).

⚠️ Error Handling

HTTP Status Codes

Status	Description
200	OK, request succeeded.
400	Bad Request, invalid parameters.
401	Unauthorized, API key missing.
403	Forbidden, invalid API key or unauthorized origin.
404	Not Found, resource does not exist (e.g. email ID not found).
429	Too Many Requests, daily quota exceeded.
500	Internal Server Error.

Error Examples

1. Missing API Key (when authentication is enabled)

{
  "success": false,
  "data": null,
  "error": "API key required"
}

2. Daily Quota Exceeded

{
  "success": false,
  "data": null,
  "error": "Daily quota exceeded"
}

3. No Active Domains Available

{
  "success": false,
  "data": null,
  "error": "No active domains available"
}

4. Unsupported Domain

{
  "success": false,
  "data": null,
  "error": "Unsupported domain"
}

📊 Notes & Limits

Domain Usage

/api/generate-email and /api/emails require that the domain be activated in the system.
If no active domains are available, the API returns "No active domains available" or a similar error.

Statistics & Privacy

Statistics endpoints return masked subjects, domains and senders, and are intended only for trend visualization.
They are not meant to expose concrete business or user data.

Quotas & Rate Limits (Suggested)

Each key has an independent daily quota; exceeding it returns HTTP 429 with "Daily quota exceeded".
Recommended throughput is no more than 10 requests per second per key to avoid throttling.

📞 Support & Feedback

If you have questions or suggestions, please contact us:

Website: https://chatgpt.org.uk
Email Service: https://mail.chatgpt.org.uk

📝 Changelog

v1.0.0 (2025-11-14)

✅ Initial version released.
✅ Support for email generation, listing, retrieval and deletion.
✅ Unified response format: {success, data, error}.
✅ Added system stats, 24-hour distribution, top subjects, top domains and top senders.
✅ Added self-service domain submission with MX validation.

⚖️ Terms of Use

Fair Use: Use the API reasonably. Abuse, brute force and quota bypassing are prohibited.
Data Privacy: Emails are retained only for a reasonable period; statistics endpoints expose masked data only.
Availability: 100% uptime is not guaranteed. Please implement retries and graceful degradation on the client side.
Prohibited Uses: No spam, phishing, malicious attacks or any illegal activity.

Last Updated: 2025-11-20

Anonymous November 15, 2025 at 8:49 AM

邮件里有图片，图片上写着验证码，无法正常显示
- ChatGPT November 15, 2025 at 8:52 AM
  
  暂时还不支持附件，这个功能后续会添加。
- Anonymous November 20, 2025 at 3:33 AM
  
  多次尝试无法收到验证码
- ChatGPT November 20, 2025 at 9:29 AM
  
  已经修复了
Anonymous November 16, 2025 at 4:20 AM

库存没了
- AIblog November 16, 2025 at 5:37 AM
  
  测试key还有额度的。