Mail Verification Code API

Version v2.0 · HOST: https://usp.lol

鉴权说明
1. 购买邮箱验证码 /openapi/v2/mail/code/buy
2. 获取邮箱验证码 /openapi/v2/mail/code
3. 释放订单（退款）/shop/api/release
4. 订单列表 /shop/api/orders
5. 账户信息 /shop/api/me
6. 产品列表 /shop/api/products
响应状态码总览
产品编号

🔐 鉴权说明

API Key

所有商店 API 需要账户 API Key。注册登录后在控制台查看。

鉴权方式	位置	参数名	适用路由
Query 参数	URL	`apiKey=usk_xxxxxx`	`/openapi/v2/*`
Header	HTTP Header	`X-Shop-Key: usk_xxxxxx`	`/shop/api/*`

API Key 格式：usk_ + 32 位随机字符。无效/缺失统一返回 code:-1 msg:"invalid"（防止枚举）。

1. 购买邮箱验证码

GET/openapi/v2/mail/code/buy扣费

按产品下单，分配一个 Gmail 邮箱。成功后账户余额扣减对应产品价格。

请求参数

参数	位置	类型	必填	说明
`apiKey`	query	string	是	账户 API Key（`usk_xxxx`）
`productCode`	query	string	是	产品编号，见产品列表

请求示例

curl "https://usp.lol/openapi/v2/mail/code/buy?apiKey=usk_xxxxxx&productCode=1003"

成功响应 200 · code=0

{
  "successful": true,
  "code": 0,
  "msg": "successful",
  "timestamp": 1749257137057,
  "data": {
    "orderNo": "N17740401a314134",
    "orderDetail": {
      "address": "hffub6795@gmail.com",
      "url": "https://usp.lol/openapi/v2/mail/code?apiKey=usk_xxxxxx&orderNo=N17740401a314134"
    }
  }
}

失败响应

场景	code	msg
apiKey 无效	-1	invalid apiKey
productCode 缺失/不存在	-1	invalid product
余额不足	-1	insufficient balance
无库存（该产品下所有 gmail 都已售出）	-1	no stock

{
  "successful": false,
  "code": -1,
  "msg": "no stock",
  "timestamp": 1749257137057,
  "data": null
}

同一 Gmail 对同一产品只能购买一次（UNIQUE(email,product_code)）。如需复用请先释放或联系管理员。

2. 获取邮箱验证码

GET/openapi/v2/mail/code

轮询接口，获取该订单邮箱收到的最新验证码（来自匹配发件人的邮件，最近 5 分钟内）。

请求参数

参数	位置	类型	必填	说明
`apiKey`	query	string	是	账户 API Key
`orderNo`	query	string	是	订单号（来自购买接口）

请求示例

curl "https://usp.lol/openapi/v2/mail/code?apiKey=usk_xxxxxx&orderNo=N17740401a314134"

成功响应 code=0

timestamp 为邮件实际收到时间（毫秒），非服务器当前时间。

{
  "successful": true,
  "code": 0,
  "msg": "ok",
  "timestamp": 1757044065330,
  "data": {
    "code": "707107",
    "email": "hffub6795@gmail.com",
    "subject": "Verify your Apple Account email address"
  }
}

等待中 code=-2

邮件尚未到达，请继续轮询（建议间隔 2-5 秒）。

{
  "successful": false,
  "code": -2,
  "msg": "waiting",
  "timestamp": 1757044065330,
  "data": null
}

订单无效 / 过期 code=-1

{
  "successful": false,
  "code": -1,
  "msg": "invalid",
  "timestamp": 1757044065330,
  "data": null
}

取码策略：
• 仅返回订单对应邮箱收到、最近 5 分钟 内、未被使用的验证码
• 按发件人域名过滤（如 Apple 产品只认 apple.com 发件）
• 首次获取成功后自动标记为已使用 + 订单 status=delivered，再次请求直接返回缓存
• 建议轮询 20-60 秒，平均 5-15 秒可命中

3. 释放订单（退款）

POST/shop/api/release需 X-Shop-Key

未交付订单可主动释放，邮箱回到库存，款项全额退回余额。已交付订单不可释放。

请求

curl -X POST "https://usp.lol/shop/api/release"   -H "X-Shop-Key: usk_xxxxxx"   -H "Content-Type: application/json"   -d '{"orderNo":"N17740401a314134"}'

成功响应

{
  "ok": true,
  "refundedCents": 150,
  "email": "hffub6795@gmail.com"
}

失败响应

场景	HTTP	error
未带 X-Shop-Key	401	unauthorized
订单不存在/非本人	404	order not found
订单已交付	400	already delivered, cannot release

4. 订单列表

GET/shop/api/orders需 X-Shop-Key

返回当前账户最近 100 条订单。

curl "https://usp.lol/shop/api/orders" -H "X-Shop-Key: usk_xxxxxx"

响应

{
  "ok": true,
  "orders": [
    {
      "order_no": "N17740401a314134",
      "product_code": "1003",
      "email": "hffub6795@gmail.com",
      "status": "delivered",
      "code": "707107",
      "price_cents": 150,
      "created_at": 1777040100000,
      "delivered_at": 1777040418000
    }
  ]
}

status: pending（未取码） / delivered（已交付）

5. 账户信息

GET/shop/api/me需 X-Shop-Key

curl "https://usp.lol/shop/api/me" -H "X-Shop-Key: usk_xxxxxx"

{
  "ok": true,
  "user": {
    "id": 1,
    "username": "demo",
    "api_key": "usk_xxxxxx",
    "balance_cents": 9650,
    "created_at": 1776900000000
  }
}

6. 产品列表

GET/shop/api/products公开

返回所有在售产品及实时库存。库存 = 该产品未被购买过的 Gmail 账户数。

curl "https://usp.lol/shop/api/products"

{
  "ok": true,
  "products": [
    {
      "product_code": "1003",
      "name": "Apple",
      "icon": "https://cdn.simpleicons.org/apple",
      "price_cents": 150,
      "sender_filter": "apple.com",
      "enabled": 1,
      "sort_order": 1,
      "stock": 2
    }
  ]
}

📋 响应状态码总览

code	successful	含义	处理建议
`0`	true	成功	读取 `data`
`-1`	false	失败 / 无效（订单、apiKey、产品、余额、库存等均返回此码）	停止重试，检查参数或账户状态
`-2`	false	等待中 / 未收到验证码	间隔 2-5s 继续轮询
`-3`	false	订单过期 / 邮箱无效	停止重试，重新购买

安全：失败场景统一 code:-1 msg:"invalid"，不区分"订单不存在"、"apiKey 错误"、"产品不存在"等，防止枚举攻击。

🛍 产品编号

Product	Product Code	价格	发件人过滤
Apple	`1003`	¥1.50	`apple.com`
Google	`1001`	¥1.00	`google.com`
Instagram	`1002`	¥1.00	`instagram.com`
PayPal	`1004`	¥1.50	`paypal.com`
Facebook	`1005`	¥1.00	`facebook.com`
Amazon	`1007`	¥1.00	`amazon.com`
Walmart	`1008`	¥1.00	`walmart.com`
Telegram	`1011`	¥1.00	`telegram.org`
Pairs	`1012`	¥1.20	`pairs`
TikTok	`1013`	¥1.00	`tiktok.com`
ChatGPT	`1014`	¥1.50	`openai.com`
X / Twitter	`1015`	¥1.00	`x.com`
LinkedIn	`1016`	¥1.00	`linkedin.com`
TextMe	`6015`	¥1.00	`textmeapp`
AWS	`6017`	¥1.50	`amazon`

💡 完整接入示例（Python）

import requests, time
API_KEY = "usk_xxxxxx"
BASE = "https://usp.lol"

# 1. 下单
r = requests.get(f"{BASE}/openapi/v2/mail/code/buy",
    params={"apiKey": API_KEY, "productCode": "1003"}).json()
assert r["code"] == 0, r["msg"]
order_no = r["data"]["orderNo"]
email = r["data"]["orderDetail"]["address"]
print(f"分配邮箱: {email}")

# 2. 前往目标站（如 Apple 注册）触发发码给 email

# 3. 轮询取码
for _ in range(30):
    r = requests.get(f"{BASE}/openapi/v2/mail/code",
        params={"apiKey": API_KEY, "orderNo": order_no}).json()
    if r["code"] == 0:
        print("验证码:", r["data"]["code"])
        break
    if r["code"] in (-1, -3):
        print("失败:", r["msg"]); break
    time.sleep(3)