注册用户 API 接入文档

接入流程

1. 创建邮箱POST /mailboxes，通过 product_code 选择 Gmail 或 iCloud。
2. 触发验证码把返回的邮箱填入目标网站，并在目标网站点击“发送验证码”。
3. 长轮询取码GET /mailboxes/{id}/codes?wait_seconds=60，验证码到达后立即返回。
4. 下一码第一码到达后，先 POST /next-code，再继续轮询，直到商品上限。
5. 结束订单已交付验证码用 complete；首码交付前可用 cancel 退款。服务端也会周期核对未结束订单。

curl "$BASE_URL/products" \
  -H "Authorization: Bearer $API_KEY"

200 响应

{
  "items": [
    {
      "product_code": "GMAIL_24H",
      "name": "Gmail 24小时邮箱",
      "domain": "gmail.com",
      "duration_hours": 24,
      "max_codes": 3,
      "price_cents": 50,
      "currency": "CNY",
      "cdk_enabled": true,
      "balance_enabled": true,
      "api_enabled": true,
      "available": true
    },
    {
      "product_code": "ICLOUD_24H",
      "name": "iCloud 24小时邮箱",
      "domain": "icloud.com",
      "duration_hours": 24,
      "max_codes": 5,
      "price_cents": 20,
      "currency": "CNY",
      "cdk_enabled": true,
      "balance_enabled": true,
      "api_enabled": true,
      "available": true
    }
  ]
}

available表示至少一个销售入口开放；API调用必须以api_enabled为准，网页CDK和余额入口分别读取cdk_enabled、balance_enabled。兼容接口 GET /product继续只返回Gmail。

curl "$BASE_URL/balance" \
  -H "Authorization: Bearer $API_KEY"

200 响应

{
  "balance_cents": 1000,
  "frozen_balance_cents": 0,
  "currency": "CNY"
}

Idempotency-Key 必填，长度 8–200，只接受字母、数字和 ._:-。网络重试必须继续使用原值与原请求体。

product_code可选：GMAIL_24H或ICLOUD_24H。不传时继续申请Gmail，兼容现有客户端。

client_reference 可选，最长 120 字符，用于关联你自己的订单号。

批量调用可并行提交：网关允许同一来源最多 300 个在途 API 请求，并以 100 请求/秒接收突发流量；真实上游采购由服务器按 12 路并行执行，其余请求自动排队。排队超时后请使用原 Idempotency-Key 重试。

curl -X POST "$BASE_URL/mailboxes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_20260723_0001" \
  -d '{"product_code":"ICLOUD_24H","client_reference":"YOUR_ORDER_0001"}'

201 响应

{
  "mailbox": {
    "id": "mbx_xxx",
    "product_code": "ICLOUD_24H",
    "product_name": "iCloud",
    "domain": "icloud.com",
    "status": "ACTIVE",
    "email": "example@icloud.com",
    "price_cents": 20,
    "currency": "CNY",
    "received_codes": 0,
    "max_codes": 5,
    "created_at": "2026-07-23T13:00:00.000Z",
    "expires_at": "2026-07-24T13:00:00.000Z"
  },
  "billing": {
    "order_price_cents": 20,
    "charged_cents": 20,
    "refunded_cents": 0,
    "net_charge_cents": 20,
    "balance_after_cents": 980,
    "frozen_balance_cents": 0,
    "key_limit_cents": 500,
    "key_spent_cents": 20,
    "key_remaining_cents": 480,
    "currency": "CNY"
  }
}

curl "$BASE_URL/mailboxes/$MAILBOX_ID" \
  -H "Authorization: Bearer $API_KEY"

响应结构为 {"mailbox": Mailbox, "billing": Billing}，账务快照用于核对余额和 Key 剩余额度。

wait_seconds 为0–60秒；after_sequence 传客户端已经处理的最后序号。新验证码到达、订单结束或等待超时都会返回。重复查询同一验证码不会增加次数。

curl "$BASE_URL/mailboxes/$MAILBOX_ID/codes?wait_seconds=60&after_sequence=0" \
  -H "Authorization: Bearer $API_KEY"

200 响应

{
  "mailbox": {
    "id": "mbx_xxx",
    "status": "CODE_RECEIVED",
    "received_codes": 1,
    "max_codes": 3
  },
  "items": [
    {
      "sequence": 1,
      "code": "482913",
      "received_at": "2026-07-23T13:01:20.000Z"
    }
  ],
  "next_after_sequence": 1,
  "waited_seconds": 12.43,
  "poll_after_seconds": 5
}

首码到达后调用。成功后状态为 WAITING_NEXT_CODE，随后继续查询 /codes，直到 items.length 增加。

curl -X POST "$BASE_URL/mailboxes/$MAILBOX_ID/next-code" \
  -H "Authorization: Bearer $API_KEY"

仅在 received_codes = 0 且上游接受取消时成功。状态变为 REFUNDED，售价退回账户余额并回退 Key 已用额度；响应同时返回最新 billing。

curl -X POST "$BASE_URL/mailboxes/$MAILBOX_ID/cancel" \
  -H "Authorization: Bearer $API_KEY"

至少收到一条验证码后调用。重复调用保持 COMPLETED。

curl -X POST "$BASE_URL/mailboxes/$MAILBOX_ID/complete" \
  -H "Authorization: Bearer $API_KEY"

状态说明

错误格式与常见错误

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "账户余额不足",
    "request_id": "req_xxx"
  }
}

Node.js 自动取码示例

const BASE_URL = "https://gmail.sanqianke.xyz/v1";
const API_KEY = "YOUR_API_KEY";
const headers = { "X-API-Key": API_KEY };

const created = await fetch(`${BASE_URL}/mailboxes`, {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({ client_reference: "YOUR_ORDER_0001" })
}).then(r => r.json());

const mailboxId = created.mailbox.id;
console.log("Gmail:", created.mailbox.email);

let afterSequence = 0;
while (true) {
  const result = await fetch(
    `${BASE_URL}/mailboxes/${mailboxId}/codes?wait_seconds=60&after_sequence=${afterSequence}`,
    {
    headers
    }
  ).then(r => r.json());

  if (result.next_after_sequence > afterSequence) {
    console.log("验证码:", result.items.at(-1).code);
    break;
  }
  afterSequence = result.next_after_sequence;
}