Developer API Documentation

开发者接入文档

适用于临时邮箱地址生成、邮件查询与实时收件监听。本文档面向已经获得 API Key 的开发者与合作方。

Swagger /docs 返回首页

接入变更说明

所有开发者 API 现已启用 API Key 鉴权。
旧接口路径仍保留兼容，但 不再允许匿名调用。
如需新的 API Key，请联系管理员在后台 /admin 生成。
如存在批量任务，请优先切换至批量与增量接口，避免高频单条轮询。

1. 服务概览

Base URL

https://quanxinhdd.xyz

OpenAPI

/docs

邮件保留时长

默认 15 分钟

邮箱生成模式

随机美国风格前缀 + 随机子域名 + 域名池随机分配

2. 认证方式

推荐使用 HTTP Header 传递 API Key。所有 API 请求都应包含以下任一认证方式：

推荐方式

X-API-Key: YOUR_API_KEY

兼容方式

Authorization: Bearer YOUR_API_KEY

WebSocket 连接建议使用查询参数：?api_key=YOUR_API_KEY

3. 推荐接入模式

单任务场景：继续使用 GET /api/generate 即可。
批量任务场景：优先使用 POST /api/generate/batch?count=N。
查询邮件场景：优先使用增量查询或批量查询，避免单邮箱高频全量轮询。
实时通知场景：优先使用 WebSocket，而不是以高频轮询代替实时推送。

4. 接口说明

GET/api/generate

生成单个临时邮箱地址。

示例请求

curl "https://quanxinhdd.xyz/api/generate" \
  -H "X-API-Key: YOUR_API_KEY"

示例响应

{
  "email": "charlotte.rodriguez@k3n.quanxinhdd.xyz",
  "expires_in_minutes": 15,
  "domain": "quanxinhdd.xyz"
}

POST/api/generate/batch?count=1000

批量生成邮箱地址。适用于并发任务、批量注册、自动化流程。

示例请求

curl -X POST "https://quanxinhdd.xyz/api/generate/batch?count=1000" \
  -H "X-API-Key: YOUR_API_KEY"

说明

建议批量任务使用本接口，而不是循环发起 1000 次单独生成请求。

GET/api/emails/{email}?limit=50

查询单个邮箱的邮件列表。

示例请求

curl "https://quanxinhdd.xyz/api/emails/charlotte.rodriguez@k3n.quanxinhdd.xyz?limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

GET/api/emails/{email}?limit=50&after_id=123

增量查询新邮件。推荐用于持续轮询时减少无效数据传输。

参数	类型	说明
limit	integer	单次返回数量，默认 50，最大 200。
after_id	integer	仅返回 ID 大于该值的新邮件。

POST/api/emails/bulk

批量查询多个邮箱的邮件数据。适用于高并发、多邮箱并行任务。

示例请求

curl -X POST "https://quanxinhdd.xyz/api/emails/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "items": [
      {"email": "charlotte.rodriguez@k3n.quanxinhdd.xyz", "after_id": 120, "limit": 20},
      {"email": "emma.scott@xra0.quanxin.edu.kg", "after_id": 88, "limit": 20}
    ]
  }'

WS/ws/{email}?api_key=YOUR_API_KEY

实时监听新邮件。连接成功后会先返回一条 connected 消息，后续新邮件到达时继续推送。

示例地址

wss://quanxinhdd.xyz/ws/charlotte.rodriguez@k3n.quanxinhdd.xyz?api_key=YOUR_API_KEY

5. 返回字段说明

字段	类型	说明
email	string	生成的完整邮箱地址，请直接使用该值。
expires_in_minutes	integer	邮箱邮件默认保留分钟数。
domain	string	本次生成所使用的域名池域名。
id	integer	邮件唯一 ID，可用于后续 after_id 增量查询。
code	string\|null	从邮件正文中提取的验证码（若识别到）。

6. 常见错误码

状态码	含义	说明
200	成功	请求处理成功。
400	请求参数错误	例如邮箱格式非法、域名不受支持、批量请求体不合法等。
401	鉴权失败	未传 API Key、API Key 无效或已被禁用。
503	服务暂不可用	例如当前没有可用域名池，或生成失败需稍后重试。

7. JavaScript 示例

const API_KEY = 'YOUR_API_KEY';

async function createMailbox() {
  const res = await fetch('https://quanxinhdd.xyz/api/generate', {
    headers: { 'X-API-Key': API_KEY }
  });
  return await res.json();
}

async function createMailboxes(count) {
  const res = await fetch(`https://quanxinhdd.xyz/api/generate/batch?count=${count}`, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY }
  });
  return await res.json();
}

async function getEmailsBulk(items) {
  const res = await fetch('https://quanxinhdd.xyz/api/emails/bulk', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
    },
    body: JSON.stringify({ items })
  });
  return await res.json();
}

function watchMailbox(email, onMail) {
  const ws = new WebSocket(`wss://quanxinhdd.xyz/ws/${encodeURIComponent(email)}?api_key=${encodeURIComponent(API_KEY)}`);
  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'connected') return;
    if (data.type === 'heartbeat') return;
    if (data.type === 'email') onMail(data);
  };
  return ws;
}

8. Python 示例

import json
import requests
import websocket

base = 'https://quanxinhdd.xyz'
api_key = 'YOUR_API_KEY'
headers = {'X-API-Key': api_key}

mailbox = requests.get(f'{base}/api/generate', headers=headers).json()
email = mailbox['email']
print('邮箱:', email)

mailboxes = requests.post(f'{base}/api/generate/batch?count=100', headers=headers).json()
print('批量数量:', len(mailboxes))

bulk = requests.post(
    f'{base}/api/emails/bulk',
    headers=headers,
    json={
        'items': [
            {'email': email, 'after_id': 0, 'limit': 20},
        ]
    },
).json()
print('批量结果:', bulk)

def on_message(ws, message):
    data = json.loads(message)
    if data.get('type') == 'connected':
        return
    if data.get('type') == 'heartbeat':
        return
    if data.get('type') == 'email':
        print('新邮件:', data)

ws = websocket.WebSocketApp(
    f'wss://quanxinhdd.xyz/ws/{email}?api_key={api_key}',
    on_message=on_message,
)
ws.run_forever()

9. 最佳实践

始终直接使用接口返回的完整邮箱地址，不要自行拼接本地前缀或域名。
批量任务优先使用 /api/generate/batch 与 /api/emails/bulk。
持续查询时优先使用 after_id 做增量拉取，而不是反复全量轮询。
需要实时性时优先使用 WebSocket。
WebSocket 事件类型当前包含：connected（连接成功）、heartbeat（连接保活）与 email（新邮件事件）。
请妥善保管 API Key，避免泄露到公开仓库或前端浏览器源码中。