# 三千客邮箱 API v1

正式基址：`https://gmail.sanqianke.xyz/v1`

机器可读规范：`https://gmail.sanqianke.xyz/openapi.json`

## 鉴权

以下两种请求头任选一种：

```http
Authorization: Bearer API_KEY
```

```http
X-API-Key: API_KEY
```

API Key 不放入 URL。每个 Key 只可访问由它创建的邮箱订单。

## 1. 查询商品

```http
GET /products
```

返回当前 Key 所属注册用户可购买的 Gmail 与 iCloud 商品、实际售价、有效时长、验证码上限和销售状态。程序申请前必须检查`api_enabled`；`available`只表示至少一个销售入口开放，CDK与余额入口分别看`cdk_enabled`和`balance_enabled`。

| `product_code` | 邮箱 | 有效期 | 验证码上限 |
|---|---|---:|---:|
| `GMAIL_24H` | Gmail | 24小时 | 3次 |
| `ICLOUD_24H` | iCloud | 24小时 | 5次 |

兼容接口 `GET /product` 继续返回 Gmail 商品，旧客户端不需要修改。

iCloud商品只交付邮箱地址和OpenAI验证码，不返回Apple ID账号、密码，也不提供iCloud云服务登录。iCloud API未开放时会返回`PRODUCT_API_PAUSED`。

## 2. 查询余额

```http
GET /balance
```

金额字段均为整数分，币种为 `CNY`。

## 3. 创建邮箱

```http
POST /mailboxes
Idempotency-Key: YOUR_UNIQUE_ORDER_KEY
Content-Type: application/json

{"product_code":"ICLOUD_24H","client_reference":"YOUR_ORDER_ID"}
```

`Idempotency-Key` 必填，长度8–200。网络重试继续使用原幂等键和原请求体。

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

成功响应包含：

- `mailbox`：邮箱、状态、成交价、验证码数量和有效期；
- `billing`：扣款、退款、净扣款、账户余额、Key已用额度和剩余额度。

## 4. 查询订单

```http
GET /mailboxes/{MAILBOX_ID}
```

该接口只读订单状态，不主动查询验证码。

## 5. 长轮询验证码

```http
GET /mailboxes/{MAILBOX_ID}/codes?wait_seconds=60&after_sequence=0
```

- `wait_seconds`：0–60，0表示立即返回；
- `after_sequence`：客户端已经处理的最后验证码序号；
- 出现更大序号、订单结束或等待超时后返回；
- 响应的 `next_after_sequence` 用于下一次请求。

推荐流程：

```text
创建邮箱
→ 在目标网站发送验证码
→ /codes?wait_seconds=60&after_sequence=0
→ 保存 next_after_sequence
→ 需要下一码时调用 /next-code
→ 再次长轮询
```

## 6. 申请下一码

```http
POST /mailboxes/{MAILBOX_ID}/next-code
```

首码到达后调用，最多接收商品配置规定的验证码数量：Gmail最多3次，iCloud最多5次。

## 7. 无码取消退款

```http
POST /mailboxes/{MAILBOX_ID}/cancel
```

仅在尚未交付验证码且上游接受取消时成功。成功后：

- 订单状态变为 `REFUNDED`；
- 成交价退回账户余额；
- API Key已用额度同步回退；
- 响应返回最新 `billing` 账务快照。

后台会周期核对未结束订单；发现上游已经取消且没有验证码时，退款事务只执行一次。

## 8. 完成订单

```http
POST /mailboxes/{MAILBOX_ID}/complete
```

至少收到一条验证码后调用。

## 状态

| 状态 | 含义 |
|---|---|
| `ALLOCATING` | 正在分配 |
| `ACTIVE` | 邮箱已分配 |
| `CODE_RECEIVED` | 已收到验证码 |
| `WAITING_NEXT_CODE` | 等待下一码 |
| `COMPLETED` | 已完成 |
| `REFUNDED` | 已退款 |
| `FAILED` | 分配失败 |
| `EXPIRED` | 已过期 |

## 错误格式

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "错误说明",
    "request_id": "req_xxx"
  }
}
```

常见 HTTP 状态：`400`参数错误、`401`Key错误、`402`余额或额度不足、`403`IP白名单拦截、`404`订单不存在、`409`状态冲突、`429`请求过快、`503`上游或队列繁忙。