API Reference

平台与商品代码：25个平台 / 27种邮箱商品

通过 POST /v1/mailboxes 的 product_code 选择商品。OpenAI、GitHub 支持 Gmail / iCloud，其余平台提供 Gmail。

查询本人价格与实时状态 · 新增平台调用示例

实时价格、销售状态和权益读取 GET /v1/products 的 price_cents、api_enabled、available、max_codes、code_limit_mode、duration_hours；已购订单使用成交快照。码数为整单上限，实际发信由目标平台决定，下一码不延长截止。

WB_* 仅支持余额/API，CDK 关闭。ICLOUD_24H 使用期为24小时；表内1小时为本站上限，上游提前结束以订单状态为准。

Facebook / Instagram 新接入使用 FACEBOOK_GMAIL / INSTAGRAM_GMAIL，支持 CDK、网页余额和 API。后台每个平台一个总开关，同时控制三个入口；关闭只阻止新订单，历史订单继续按原快照收码和结算。旧 WB_FACEBOOK_GMAIL / WB_INSTAGRAM_GMAIL 继续兼容原接入，历史订单权益保持。

Facebook / Instagram Gmail 接码

原路径、鉴权和幂等方式保持。省略 product_code 仍购买 GMAIL_24H；新品显式填写平台商品编码。

POST /v1/mailboxes
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: YOUR_UNIQUE_FB_ORDER
Content-Type: application/json

{"product_code":"FACEBOOK_GMAIL","client_reference":"FB-001"}

Instagram 使用 {"product_code":"INSTAGRAM_GMAIL","client_reference":"IG-001"}。先读取 GET /v1/products 的本人价格、库存、api_enabled、available、有效期和收码规则。默认标价人民币1.00元，实扣以本人价格和建单锁价为准。

• LIMITED：最多交付 max_codes 个有效新码，本商品固定码数线路为5码；重复码不累计，达到上限后完成。
• UPSTREAM：按实际下一码开放状态处理，不承诺无限交付；无额外安全上限时 max_codes: null。不要把 null 当成0。
• 沿用 /mailboxes/{id}/codes 和 /next-code。首码到达后按能力请求下一码，随后继续轮询；明确结束或到期后停止。
• 缺货且确认未采购时恢复余额和 Key 额度；ALLOCATION_UNKNOWN 保留原单核实。已收任意码后不按无码退款。
• 商品切换只影响新订单，历史订单保留原截止时间、收码模式和换号权益。相同幂等键或客户订单号找回原单，内容冲突返回409。

接口错误格式保持；商品关闭返回原暂停类错误，取消、换号和完成继续使用原路径。Markdown · OpenAPI

多平台接入

默认商品：GMAIL_24H（OpenAI Gmail）。适用于 GET /product 及省略 product_code 的创建请求。

POST /v1/mailboxes
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: YOUR_UNIQUE_ORDER_ID
Content-Type: application/json

{
  "product_code": "WB_TELEGRAM_GMAIL",
  "client_reference": "YOUR_ORDER_ID",
  "max_price_cents": 80
}

示例商品：WB_TELEGRAM_GMAIL。替换 product_code 选择其他平台；购买条件为 api_enabled 与 available。WB_* 的 cdk_enabled=false。

launch_policy：VERIFIED_ONLY 或 OPERATOR_ACCEPTED；policy_verified 表示规则已核实，operator_accepted 表示运营批准带待核项开放，二者独立。duration_hours 为本站使用期上限（新品默认1小时），max_codes 为整单上限；实际期限及后续码资格以订单状态为准。

max_price_cents：可选成交价上限（分），超限不采购；省略使用用户当前价。幂等重放返回原成交回执。超时或 ALLOCATION_UNKNOWN 须沿用原请求核实；冻结资金不代表已交付。

POST /v1/mailboxes/MAILBOX_ID/next-code
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"target_sequence": 2}

WB_* 及采用上游下一码模式的 Facebook / Instagram 新商品必须提交 target_sequence，整数从 2 开始。持续读取模式没有独立的上游下一码开启接口，target_sequence 可省略；若提交则必须是当前下一序号且不超过5。固定5码线路最多到本单5码；采用 code_limit_mode=UPSTREAM 且未配置本站安全上限的线路由上游决定是否继续，本站接口校验上限为100，配置安全上限后不超过该上限。同一目标重试不递增；待开放或待核实时保持原目标，超限返回 409 CODE_LIMIT_REACHED。后续码包含在整单价内，不延长截止；已收码不适用无码退款。

等级累计：启用后的已结算合格净消费；退款冲减，充值、冻结款及直接CDK标价不计。库存档位：0暂无、1–99很少、100–999一般、≥1000很多；未知库存不等于0，库存不保证交付。

接入流程

1. 创建邮箱POST /mailboxes，通过 product_code 选择上表任一已开放邮箱商品。
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 1小时短效邮箱",
      "domain": "gmail.com",
      "duration_hours": 1,
      "max_codes": 3,
      "code_limit_mode": "LIMITED",
      "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
    },
    {
      "product_code": "GITHUB_GMAIL",
      "name": "GitHub 专用 Gmail 接码",
      "domain": "gmail.com",
      "duration_hours": 1,
      "max_codes": 1,
      "code_limit_mode": "LIMITED",
      "price_cents": 50,
      "currency": "CNY",
      "cdk_enabled": true,
      "balance_enabled": true,
      "api_enabled": true,
      "available": true
    },
    {
      "product_code": "GITHUB_ICLOUD",
      "name": "GitHub 专用 iCloud 接码",
      "domain": "icloud.com",
      "duration_hours": 1,
      "max_codes": 5,
      "code_limit_mode": "LIMITED",
      "price_cents": GITHUB_20,
      "currency": "CNY",
      "cdk_enabled": false,
      "balance_enabled": GITHUB_true,
      "api_enabled": GITHUB_true,
      "available": GITHUB_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，只接受字母、数字和 ._:-。网络重试必须继续使用原值与原请求体。

GMAIL_24H是保留的兼容编号。新Gmail使用期为1小时，已激活旧单以原订单截止时间为准。

product_code可传完整平台表中的原四种商品或已开放的WB_*新平台代码；以GET /products返回为准。不传时继续申请原OpenAI Gmail，兼容现有客户端。

client_reference 可选，最长 120 字符，外部业务订单号。

采购队列配置（部署参数及响应提示优先）：

网关并发、Key/IP限频与采购队列独立。429 按 Retry-After 退避；排队超时沿用原请求。客户端超时须覆盖排队和采购，长轮询超时须大于 wait_seconds。

订单固定创建时的线路、成交价及截止时间。适用到期核对退款时，仅退最后一笔合格收费权益；查询异常保持待核。客户退款与上游回款独立记账。

幂等键须跨进程持久化。重放返回原回执，含历史订单状态、balance_after_cents 和 Key 额度快照。实时状态查询订单详情，实时余额查询 GET /balance。

REQUEST_PROCESSING、ALLOCATION_UNKNOWN、REPLACEMENT_PROCESSING或网络失败时保留原请求核实，不另建采购。明确收到ALLOCATION_RESOLVED_FAILED且原费用已释放后，才为下一次明确采购建立新业务请求及新键；ALLOCATION_RESOLVED_CLOSED先查看原单，不默认再买。

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": "[email protected]",
    "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、billing、已保存 codes 及 replacement。仅读取本地记录；采购待核实的 mailbox.email 可为 null。

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

after_sequence只控制等待唤醒，不过滤结果。items含该邮箱全部已保存验证码，按mailbox.id + sequence去重，不用items.length判断新增。换号响应可能返回新mailbox.id，下次改用新ID并重置游标为0；若已含新邮箱验证码，保存其实际最大序号，不沿用旧邮箱游标。错误响应不更新游标。

/codes 查询上游，不触发目标平台发信；订单详情仅读取本地记录。

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
}

UPSTREAM 模式按实际下一码状态处理，不承诺无限交付；max_codes 可为 null。Facebook / Instagram 本站最多5码；以本单模式、上限和截止时间为准。

订单返回 code_limit_mode：LIMITED 时最多收 max_codes 条；UNLIMITED 时 max_codes: null，在订单有效期内不限次数。程序应按模式判断，避免把 null 当成零或写死3次。

OpenAI Gmail API新订单使用期最长1小时，码数以订单模式为准；GitHub Gmail固定1码、收到即完成。OpenAI Gmail单次CDK和网页余额购买均为1小时、最多3码；OpenAI iCloud为24小时、最多5码，GitHub iCloud为1小时、最多5码。实际可用性以查询结果为准。

GitHub Gmail没有第二码，调用本接口返回409 CODE_LIMIT_REACHED，不会请求开启下一码。其他多码商品首码到达后调用。成功后状态为 WAITING_NEXT_CODE，随后继续查询 /codes，处理尚未保存的更大sequence。

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

先查询原订单的replacement。kind: BALANCE为原订单链换号模式：未收码、等待期结束且原使用期内，每笔原订单3次成功免费换号，随后按当前用户商品价确认扣款，截止不延长。kind: BALANCE_REPURCHASE为退款重购模式：核对未收码并确认旧单退款，再按当前用户价购买同类邮箱，新单从成功分配起重新计时。CDK和短信规则保持。

请求必带Idempotency-Key，免费请求体为{}。付费时先展示replacement.next_price_cents并确认，再提交下列字段；当前价改变返回REPLACEMENT_PAYMENT_REQUIRED，余额/Key不足不会采购。超时继续使用原键及原请求体，不重新下单。

curl -X POST "$BASE_URL/mailboxes/$MAILBOX_ID/replace" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: replace-ORDER-0001" \
  -H "Content-Type: application/json" \
  -d '{"accept_charge":true,"expected_price_cents":50}'

返回最新邮箱及replacement/billing。旧订单ID也可找回最新成功邮箱；OpenAI Gmail API按订单码数模式处理，GitHub Gmail始终1码。allocation_price_cents是本次增量，免费为0；total_charge_cents及账务的chain_*保留累计费用。合格退款仅退当前关联成交价，不退此前已弃用的付费采购；人工双证据退款要求不变。结果待核实时原邮箱仍可查看，冻结金额核实前不额外采购。

BALANCE_REPURCHASE重购始终提交accept_charge: true与当前expected_price_cents，价格为0也需确认；refund_price_cents是旧单待退金额。退款不明确返回UPSTREAM_CANCELLATION_PENDING且不采购；退款已确认而新单缺货时保留旧单退款，稍后可继续分配。采购未知保留原请求；查询、退款核对和页面刷新不自动采购。只在用户再次确认时继续。GitHub Gmail1码，OpenAI iCloud和GitHub iCloud最多5码。

仅在 received_codes = 0 且符合本单refund_policy时成功。MANUAL_VERIFIED_ONLY须人工核实实际触发目标平台发信及邮箱风控失效，购买满30分钟并复查最终无码后办理；未发码、闲置或仅普通无码不退。UPSTREAM_CONFIRMED_NO_CODE须核查收码并确认取消退款结果，结果未确认不提前退余额。refund_eligible_at只表示最低等待时间，到点不代表审核已通过。成功后状态变为 REFUNDED，售价退回账户余额并回退 Key 已用额度；响应同时返回最新 billing，重复操作不重复退款。查码、普通无码或闲置不等于人工售后审核通过。

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

GitHub Gmail首码保存后自动完成，无需额外调用；其他商品至少收到一条验证码后调用。重复调用保持 COMPLETED。

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

状态说明

错误格式与常见错误

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

相关CDK接口还可返回410 CDK_EXPIRED或CDK_USAGE_EXPIRED；不是公开邮箱API统一过期返回。邮箱API已结束操作通常返回409 ORDER_CLOSED或终态订单。

GitHub · iCloud：余额与 API 专用

GITHUB_ICLOUD交付GitHub专用icloud.com邮箱，本站最长1小时、最多5码。仅开放网页余额和API，cdk_enabled=false；BAL余额卡仍可充值共用账户。下一码资格及实际结束时间以订单实时状态为准，1小时为本站上限。

POST /v1/mailboxes
Authorization: Bearer API_KEY
Idempotency-Key: github-icloud-order-0001
Content-Type: application/json

{"product_code":"GITHUB_ICLOUD","client_reference":"YOUR_ORDER_ID"}

售价读取当前Key的GET /products。首码后为CODE_RECEIVED，需要后续码时提交目标序号，同一目标重试保持原序号：

POST /v1/mailboxes/MAILBOX_ID/next-code
Authorization: Bearer API_KEY
Content-Type: application/json

{"target_sequence":2}

后续依次申请3、4、5并继续查码；按邮箱ID和sequence去重，重复返回的既有码不重复计数。第5码保存后完成；达到上限返回409 CODE_LIMIT_REACHED，已收码也可主动完成。

target_sequence缺失或格式错误返回400 INVALID_TARGET_SEQUENCE，跳过未交付序号返回409 NEXT_CODE_SEQUENCE_CONFLICT。遇到UPSTREAM_NEXT_CODE_PENDING或UPSTREAM_NEXT_CODE_STATUS_ERROR时，查询原订单的next_code_request及验证码，并用同一目标序号重试；不要新建订单或擅自递增目标。UPSTREAM_NEXT_CODE_NOT_READY表示上游尚未开放，等待后核查原订单。

网页余额没有手动退款，无码可申请换邮箱：先核对收码并确认旧邮箱退款，再按当前用户本商品价重购同类邮箱，新单重新计时。外接API保留原Key的取消及换号接口。到期仍无码由后台核对，上游确认取消退款后才回退人民币和Key已用额度；结果不明保持REFUND_PENDING，重复核对只结算一次。已收到任意验证码后不适用无码退款或换号。

本商品独立定价及开关；暂停新购买仍可处理已有订单。交付只有iCloud邮箱地址和GitHub验证码，不含Apple ID、邮箱密码或iCloud登录权限。

Node.js 自动取码示例

Node.js ≥22；文件名 receive-code.mjs。必填环境变量：API_KEY、持久化 ORDER_KEY；可选：PRODUCT_CODE、CLIENT_REFERENCE。重跑使用原值。示例仅取首码，不自动取消、换号或重复采购；目标平台发信需单独触发。

const BASE_URL = process.env.BASE_URL || "https://gmail.sanqianke.xyz/v1";
const API_KEY = process.env.API_KEY;
const ORDER_KEY = process.env.ORDER_KEY;
if (!API_KEY || !ORDER_KEY) throw new Error("请设置API_KEY及持久保存的ORDER_KEY");
const headers = { "X-API-Key": API_KEY };
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
let deadline = Date.now() + 60 * 60_000;

async function pause(ms) {
  const remaining = deadline - Date.now();
  if (remaining <= 0) throw new Error("已到示例总超时或订单截止，请查看原订单");
  await sleep(Math.min(ms, remaining));
  if (Date.now() >= deadline) throw new Error("已到示例总超时或订单截止，请查看原订单");
}

async function request(path, options = {}, timeoutMs = 75_000) {
  for (let attempt = 0; attempt < 6; attempt++) {
    let retryAfterMs = 0;
    try {
      const remaining = deadline - Date.now();
      if (remaining <= 0) throw Object.assign(new Error("已到请求截止"), { fatal: true });
      const response = await fetch(`${BASE_URL}${path}`, {
        ...options, headers: { ...headers, ...options.headers },
        signal: AbortSignal.timeout(Math.min(timeoutMs, remaining))
      });
      let data;
      try { data = await response.json(); }
      catch {
        if (response.ok) throw Object.assign(new Error("响应不是JSON，保留原请求核实"), { fatal: true });
      }
      if (response.ok) {
        if (!data || typeof data !== "object" || data.error) {
          throw Object.assign(new Error("响应结构异常，保留原请求核实"), { fatal: true });
        }
        return data;
      }
      const code = data?.error?.code || `HTTP_${response.status}`;
      const transient = [429, 500, 502, 503, 504].includes(response.status)
        || ["REQUEST_PROCESSING", "REPLACEMENT_PROCESSING", "MAILBOX_BUSY", "ALLOCATION_UNKNOWN"].includes(code);
      const value = response.headers.get("Retry-After");
      const wait = /^\d+(\.\d+)?$/.test(value || "")
        ? Number(value) * 1000 : Date.parse(value) - Date.now();
      if (Number.isFinite(wait)) retryAfterMs = Math.max(0, wait);
      const requestId = data?.error?.request_id;
      throw Object.assign(new Error(`${code}${requestId ? ` (${requestId})` : ""}`), {
        fatal: !transient || ["PRODUCT_API_PAUSED", "SALES_PAUSED"].includes(code)
      });
    } catch (error) {
      if (error.fatal || attempt === 5) throw error;
    }
    await pause(Math.max(retryAfterMs, Math.min(30_000, 1000 * 2 ** attempt)));
  }
}

function validateMailbox(mailbox) {
  if (!mailbox || typeof mailbox.id !== "string" || !mailbox.id
      || typeof mailbox.status !== "string" || !Number.isFinite(Date.parse(mailbox.expires_at))) {
    throw new Error("邮箱响应不完整，保留原请求核实");
  }
}

const created = await request("/mailboxes", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": ORDER_KEY
  },
  body: JSON.stringify({
    product_code: process.env.PRODUCT_CODE || "GMAIL_24H",
    client_reference: process.env.CLIENT_REFERENCE || ORDER_KEY
  })
}, 180_000);

validateMailbox(created.mailbox);
let mailboxId = created.mailbox.id;
deadline = Math.min(deadline, Date.parse(created.mailbox.expires_at));
console.log("邮箱:", created.mailbox.email, "订单:", mailboxId);

let afterSequence = 0;
const seen = new Set();
const ended = new Set(["COMPLETED", "REFUNDED", "REFUND_PENDING", "CANCELED", "FAILED", "EXPIRED"]);
while (Date.now() < deadline) {
  const result = await request(`/mailboxes/${encodeURIComponent(mailboxId)}/codes?wait_seconds=60&after_sequence=${afterSequence}`);
  validateMailbox(result.mailbox);
  if (!Array.isArray(result.items) || !Number.isSafeInteger(result.next_after_sequence)
      || result.next_after_sequence < 0 || result.items.some(item =>
        !item || typeof item !== "object" || !Number.isSafeInteger(item.sequence)
        || item.sequence < 1 || typeof item.code !== "string" || !item.code)) {
    throw new Error("查码响应不完整，保留原游标和订单核实");
  }
  const changed = result.mailbox.id !== mailboxId;
  if (changed) { mailboxId = result.mailbox.id; afterSequence = 0; }
  deadline = Math.min(deadline, Date.parse(result.mailbox.expires_at));
  let received = false;
  for (const item of result.items) {
    const key = `${mailboxId}:${item.sequence}`;
    if (!seen.has(key)) {
      seen.add(key);
      console.log("验证码:", item.code, "序号:", item.sequence);
      received = true;
    }
  }
  const lastSaved = Math.max(0, ...result.items.map(item => item.sequence));
  afterSequence = changed ? lastSaved : Math.max(afterSequence, lastSaved, result.next_after_sequence);
  if (received || ended.has(result.mailbox.status)) break;
  const pollMs = Number(result.poll_after_seconds) * 1000;
  await pause(Number.isFinite(pollMs) ? Math.max(1000, pollMs) : 5000);
}

重试上限6次，优先按 Retry-After 退避。运行上限为1小时与 expires_at 的较早者，停止不触发退款。后续码调用 /next-code 后按原邮箱游标继续查询。