MailBox
首页 我的订单 邮箱取件 开发者 API

开发者 API

Base URL:

验证码 API

使用购买邮箱时获得的订单 access_key 获取当前订单创建后收到的最新验证码。

GET /api/v1/verification-code
Authentication
X-Access-Key: <access_key>
Pending
status: "pending"
Received
status: "received"
Mail Received
status: "mail_received"

请求参数

位置字段类型必填说明
HeaderX-Access-Keystring是购买邮箱时获得的订单 access key。

所有 API 时间均为带 +08:00 偏移的 ISO 8601 上海时间。调用方应解析为时间戳后再比较，不要删除时区偏移。

200 响应字段

字段类型说明
statusstringpending、mail_received 或 received
codestring | null识别出的验证码；未识别时为 null
received_atstring | null最新邮件接收时间，ISO 8601 格式
messageobject | null最新邮件的主题、发件人、纯文本正文和链接；不返回可执行 HTML

200 Received

application/json

{
  "status": "received",
  "code": "123456",
  "received_at": "2026-07-10T11:30:12+08:00",
  "message": {
    "subject": "Your verification code",
    "body_text": "Your verification code is 123456",
    "links": [],
    "verification_code": "123456"
  }
}

200 Pending

application/json

{
  "status": "pending",
  "code": null,
  "received_at": null,
  "message": null
}

200 Mail Received

application/json

{
  "status": "mail_received",
  "code": null,
  "received_at": "2026-07-10T11:30:12+08:00",
  "message": {
    "subject": "New verification template",
    "body_text": "Open the secure link to continue",
    "links": ["https://example.com/verify"]
  }
}

curl

curl "/api/v1/verification-code" \\
  -H "X-Access-Key: <access_key>"

Python requests

import requests

response = requests.get(
    "/api/v1/verification-code",
    headers={"X-Access-Key": "<access_key>"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

JavaScript fetch（每 20 秒轮询）

const accessKey = "<access_key>";

async function waitForCode() {
  while (true) {
    const response = await fetch("/api/v1/verification-code", {
      headers: { "X-Access-Key": accessKey },
    });
    if (!response.ok) throw new Error(`Request failed: ${response.status}`);
    const result = await response.json();
    if (result.status === "received") return result.code;
    if (result.status === "mail_received") return result.message;
    await new Promise((resolve) => setTimeout(resolve, 20000));
  }
}

console.log(await waitForCode());
HTTP 状态含义
200pending 表示尚无新邮件；mail_received 表示邮件已到但未识别出验证码，可读取 message；received 表示可读取 code。
401未提供 X-Access-Key。
404access key 不可用或订单已失效。
429请求频率超限；读取 Retry-After 后再试。
503限流服务暂不可用，请稍后重试。

邮件列表 API

返回当前订单创建后收到的最近邮件。默认 10 封，最多 50 封，仅返回纯文本正文与提取出的链接。

GET /api/v1/messages?limit=10 
curl "/api/v1/messages?limit=10" \\
  -H "X-Access-Key: <access_key>"

批量验证码 API

单次查询最多 100 个邮箱。每项使用独立 access key，响应通过非敏感 ref 与请求对应。

POST /api/v1/verification-codes/batch

Request

application/json

{
  "items": [
    {
      "ref": "mail-1",
      "access_key": "<access_key_1>"
    },
    {
      "ref": "mail-2",
      "access_key": "<access_key_2>"
    }
  ]
}

200 Response

application/json

{
  "summary": {
    "requested": 2,
    "received": 1,
    "mail_received": 0,
    "pending": 1,
    "failed": 0
  },
  "items": [
    {
      "ref": "mail-1",
      "status": "received",
      "address": "first@icloud.com",
      "code": "123456",
      "received_at": "2026-07-10T11:30:12+08:00",
      "expires_at": "2026-08-10T11:30:12+08:00"
    },
    {
      "ref": "mail-2",
      "status": "pending",
      "address": "second@icloud.com",
      "code": null,
      "received_at": null,
      "expires_at": "2026-08-10T11:30:12+08:00"
    }
  ]
}
字段约束说明
items1-100access key 列表；ref 和 access_key 均不可重复。
ref1-64 字符客户端关联标识，响应会原样返回。
status枚举received、mail_received、pending、expired 或 not_found。

经销商 API

账户级接口需要在每个请求中携带 X-API-Key。

MethodEndpoint用途
GET/api/v1/products查询商品与库存
GET/api/v1/balance查询账户余额
POST/api/v1/orders创建订单
GET/api/v1/orders/{order_no}查询订单
GET/api/v1/inbox/{access_key}读取订单收件箱
POST/api/v1/inboxes/batch批量读取当前账户拥有的收件箱

GET/api/v1/products

查询商品、有效期档位与库存。

periods[].days 为可购买天数；tiers[].min_qty 与 tiers[].unit_price 为阶梯价格。

200 Response

application/json

{
  "products": [
    {
      "id": "icloud",
      "name": "iCloud 邮箱",
      "provider_type": "icloud",
      "periods": [
        {
          "days": 30,
          "tiers": [
            {
              "min_qty": 1,
              "unit_price": 0.5
            }
          ]
        }
      ],
      "stock": 24
    }
  ]
}

GET/api/v1/balance

查询账户余额，balance 的类型为 number。

200 Response

application/json

{
  "balance": 100.5
}

POST/api/v1/orders

创建并交付订单。provider_type 为商品 ID；quantity 必填且范围为 1-100；duration_days 可选，缺省时使用默认有效期。

每个交付邮箱包含 address、access_key 和 expires_at。

Request Body

application/json

{
  "provider_type": "icloud",
  "quantity": 2,
  "duration_days": 30
}

200 Response

application/json

{
  "order_no": "MM20260710...",
  "quantity": 2,
  "duration_days": 30,
  "unit_price": 0.5,
  "total": 1.0,
  "emails": [
    {
      "address": "user@icloud.com",
      "access_key": "<access_key>",
      "expires_at": "2026-08-09T11:30:12+08:00"
    }
  ]
}

GET/api/v1/orders/{order_no}

路径参数 order_no 为订单号；仅返回当前 API 账户拥有的订单。

200 Response

application/json

{
  "order_no": "MM20260710...",
  "status": "completed",
  "quantity": 2,
  "total_amount": 1.0,
  "created_at": "2026-07-10T11:30:12+08:00",
  "emails": []
}

GET/api/v1/inbox/{access_key}

路径参数 access_key 为订单密钥，响应返回邮箱信息和最近邮件。

该接口返回邮件正文，仅应在服务端调用，不要写入浏览器或应用日志。

200 Response

application/json

{
  "address": "user@icloud.com",
  "expires_at": "2026-08-09T11:30:12+08:00",
  "messages": [
    {
      "from": "sender@example.com",
      "subject": "Verification code",
      "body": "Your code is 123456",
      "verification_code": "123456",
      "received_at": "2026-07-10T11:30:12+08:00"
    }
  ]
}

POST/api/v1/inboxes/batch

单次最多 20 个 access key，仅返回当前 X-API-Key 客户名下的邮箱；其他客户的 key 按 not_found 处理。

Request

application/json

{
  "items": [
    {
      "ref": "mail-1",
      "access_key": "<access_key_1>"
    }
  ],
  "message_limit": 10
}

200 Response

application/json

{
  "summary": {
    "requested": 1,
    "succeeded": 1,
    "failed": 0
  },
  "items": [
    {
      "ref": "mail-1",
      "status": "ok",
      "inbox": {
        "address": "user@icloud.com",
        "expires_at": "2026-08-09T11:30:12+08:00",
        "messages": []
      }
    }
  ]
}