DEVELOPER API · V1

注册用户 API 接入文档

创建 Key、申请 Gmail、自动轮询验证码、按需接收第二码和第三码。

本地测试http://localhost:3000/v1

正式域名https://gmail.sanqianke.xyz/v1

鉴权Authorization: Bearer API_KEY

API Key 在用户中心创建，完整值只显示一次。所有金额字段均为整数分；售价按 Key 所属注册用户单独返回，不设置公开统一价。每个 Key 只可访问由它创建的订单。

export BASE_URL="https://gmail.sanqianke.xyz/v1"
export API_KEY="YOUR_API_KEY"

接入流程

创建邮箱POST /mailboxes，保存返回的 MAILBOX_ID 和 Gmail 地址。
触发验证码把 Gmail 填入目标网站，并在目标网站点击“发送验证码”。
轮询取码每 5 秒 GET /mailboxes/{id}/codes，直到 items 出现新验证码。
下一码第一码到达后，先 POST /next-code，再继续轮询；最多三条。
结束订单已交付验证码用 complete；首码交付前可用 cancel 退款。

GET/product

查询当前用户售价和商品状态

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

200 响应

{
  "id": "gmail_24h",
  "name": "Gmail 24 小时短效邮箱",
  "domain": "gmail.com",
  "duration_hours": 24,
  "max_codes": 3,
  "price_cents": USER_PRICE_CENTS,
  "pricing_source": "CUSTOM",
  "currency": "CNY",
  "available": true
}

GET/balance

查询账户可用余额

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

200 响应

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

POST/mailboxes

申请邮箱并从账户余额扣款

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

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 '{"client_reference":"YOUR_ORDER_0001"}'

201 响应

{
  "mailbox": {
    "id": "mbx_xxx",
    "status": "ACTIVE",
    "email": "example@gmail.com",
    "price_cents": USER_PRICE_CENTS,
    "currency": "CNY",
    "received_codes": 0,
    "max_codes": 3,
    "created_at": "2026-07-23T13:00:00.000Z",
    "expires_at": "2026-07-24T13:00:00.000Z"
  }
}

GET/mailboxes/{MAILBOX_ID}

查询订单状态，不触发取码

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

响应结构为 {"mailbox": Mailbox}。

GET/mailboxes/{MAILBOX_ID}/codes

向上游查询验证码

目标网站发送验证码后，每 5 秒请求一次。重复查询同一验证码不会增加次数。

curl "$BASE_URL/mailboxes/$MAILBOX_ID/codes" \
  -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"
    }
  ],
  "poll_after_seconds": 5
}

POST/mailboxes/{MAILBOX_ID}/next-code

开始接收第二码或第三码

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

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

POST/mailboxes/{MAILBOX_ID}/cancel

首码交付前取消并退款

仅在 received_codes = 0 时使用。成功后状态为 REFUNDED，售价退回账户余额并回退 Key 已用额度。

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

POST/mailboxes/{MAILBOX_ID}/complete

验证码使用完成后结束订单

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

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

状态说明

ALLOCATING正在分配邮箱

ACTIVE邮箱已分配，等待目标网站发码

CODE_RECEIVED已收到验证码

WAITING_NEXT_CODE等待第二码或第三码

COMPLETED订单已完成

REFUNDED无码取消，余额已退回

FAILED分配失败，扣费已自动退回

EXPIRED订单已过期

错误格式与常见错误

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

HTTP	错误码	含义
400	`IDEMPOTENCY_REQUIRED` / `INVALID_IDEMPOTENCY_KEY`	创建请求缺少或误填幂等键
401	`INVALID_API_KEY`	Key 错误、已停用，或所属用户已停用
402	`INSUFFICIENT_BALANCE` / `KEY_LIMIT_EXCEEDED`	余额或 Key 消费额度不足
403	`KEY_IP_REJECTED`	调用 IP 不在白名单
404	`MAILBOX_NOT_FOUND`	订单不存在，或该订单不属于当前 Key
409	`IDEMPOTENCY_CONFLICT` / `ORDER_CLOSED` / `CODE_LIMIT_REACHED`	重复请求冲突或订单状态不允许操作
429	`KEY_RATE_LIMITED` / `RATE_LIMITED`	Key 或来源 IP 请求过快
503	`SALES_PAUSED` / `UPSTREAM_UNAVAILABLE` / `ALLOCATION_QUEUE_FULL` / `ALLOCATION_QUEUE_TIMEOUT`	商品暂停、上游分配失败或批量申请排队超限；失败订单自动退款

Node.js 自动取码示例

const BASE_URL = "https://gmail.sanqianke.xyz/v1";
const API_KEY = "YOUR_API_KEY";
const headers = { Authorization: `Bearer ${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);

while (true) {
  const result = await fetch(`${BASE_URL}/mailboxes/${mailboxId}/codes`, {
    headers
  }).then(r => r.json());

  if (result.items.length) {
    console.log("验证码:", result.items.at(-1).code);
    break;
  }
  await new Promise(resolve => setTimeout(resolve, 5000));
}