收信 API

给程序和 AI 对话用的接口，主要用途是自动拿验证码。不需要浏览器，也不需要把账号密码交出去，只要一把 API Key。

先登录就能看到你自己的 Key。本页的接口说明不登录也能看。

把这段话发给别的 AI 对话，它就会用了

已经把你的 Key 和完整流程写进去了，复制粘贴过去即可，不用再解释。

你可以调用一个临时邮箱收信 API 来自动获取注册验证码。

接口根地址：https://mail.cylihui.com/api/v1
认证：所有请求带请求头  Authorization: Bearer h7k_你的APIKey
（也可以图省事直接在 URL 后加 ?key=h7k_你的APIKey）

【最常用的流程：注册某网站并拿到验证码】
1) 开一个新邮箱（也可以用已有的，跳过这步）：
   curl -s -X POST "https://mail.cylihui.com/api/v1/mailboxes" -H "Authorization: Bearer h7k_你的APIKey"
   返回：{"ok":true,"id":123,"address":"ab12cd34ef@dasen-nc.com"}
   拿到 address，用它去目标网站注册。

2) 记下当前游标（重要，避免拿到旧验证码）：
   curl -s "https://mail.cylihui.com/api/v1/code?address=邮箱地址" -H "Authorization: Bearer h7k_你的APIKey"
   返回里的 "cursor" 记下来，比如 4410。

3) 在目标网站点「发送验证码」。

4) 挂着等新验证码到达（一个请求最多阻塞 55 秒）：
   curl -s "https://mail.cylihui.com/api/v1/code?address=邮箱地址&after_id=4410&wait=55" -H "Authorization: Bearer h7k_你的APIKey"
   命中：{"ok":true,"found":true,"code":"123456","kind":"code","expiresIn":540,"message":{...}}
   没到：{"ok":true,"found":false,"cursor":4410,...}  → 用同样参数再请求一次即可继续等。
   直接读 "code" 字段填进网站就行。

【要点】
- found=false 不是错误，只是还没到，重试即可。判断成败只看 "ok"。
- 一定要传 after_id（用上一次返回的 cursor），否则可能拿到邮箱里的旧验证码。
- wait 最大 55 秒。服务器同时最多 4 个请求在等，挤满时会立刻返回并带 waitSkipped=true，隔几秒重试。
- 默认只返回验证码。想要验证链接之类，加 kind=link 或 kind=any。
- 每个 Key 每分钟最多 300 次调用，超了返回 HTTP 429。
- 出错时返回 {"ok":false,"error":"简短错误码","message":"中文说明"}，按 message 说的改就行。

【其他端点】
GET  /api/v1/ping                      验证 Key 是否可用
GET  /api/v1/mailboxes                 列出所有邮箱（参数 q 搜索、page、limit）
POST /api/v1/mailboxes                 新开邮箱（参数 note 备注，可选）
GET  /api/v1/messages?address=X        列该邮箱最近邮件（参数 limit、after_id、unread=1）
GET  /api/v1/messages/123              单封详情，含正文 text / html
POST /api/v1/read                      标为已读（参数 address 整箱，或 message_id 单封）

注意：这个 Key 不能删邮箱、不能改密码。

认证

三种写法都认，任选其一：

Authorization: Bearer h7k_你的APIKey
X-API-Key: h7k_你的APIKey
?key=h7k_你的APIKey

Key 在注册时自动生成，一个账号同时只有一把。泄露了到账号设置重置，旧的立即失效。

端点

方法与路径	说明	参数
`GET /api/v1/`	端点自述，不需要 Key	—
`GET /api/v1/ping`	验证 Key，回账号名、邮箱数、配额、未读数	—
`GET /api/v1/mailboxes`	列出自己的邮箱	`q` 搜地址、`page`、`limit`(≤200)
`POST /api/v1/mailboxes`	新开一个邮箱，返回地址	`note` 备注（可选）
`GET /api/v1/messages`	列某邮箱最近邮件	`address` 必填、`limit`(≤100)、`after_id`、`unread=1`
`GET /api/v1/messages/{id}`	单封详情，含正文 `text`/`html`	`mark_read=1`（可选）
`GET /api/v1/code`	核心：取最新验证码，可阻塞等待	见下
`POST /api/v1/read`	标为已读	`address` 整箱，或 `message_id` 单封

`GET /api/v1/code` 的参数

参数	默认	说明
`address`	必填	邮箱完整地址。也可以用 `mailbox_id` 代替
`wait`	0	没有新验证码时最多挂起多少秒（上限 55）。0 表示查一次就返回
`after_id`	—	只要 id 比它大的邮件。传上一次返回的 `cursor`，就绝不会拿到旧码
`since`	—	只要这个时刻之后的邮件。unix 秒或时间字符串。用了 wait 又没传 after_id/since 时，默认只看最近 2 分钟
`kind`	`code`	要哪类内容。可写 `code,link` 这样的多值，或 `any` 表示不限
`mark_read`	0	传 1 则命中后顺手把那封标为已读

// 拿到了
{
  "ok": true, "found": true,
  "code": "123456",            // 直接可用的值（链接类则是完整 URL）
  "kind": "code",              // code/link/password/2fa/promo/id/notice
  "label": "验证码",
  "expiresIn": 540,            // 剩余有效秒数，null 表示邮件没写有效期
  "cursor": 4411,              // 下次当 after_id 传回来
  "waited": 12.3,              // 本次实际等了多少秒
  "message": { "id": 4411, "from": "...", "subject": "...", "items": [...] }
}

// 还没到（不是错误）
{ "ok": true, "found": false, "cursor": 4410, "hint": "...", "waitSkipped": false }

// 出错
{ "ok": false, "error": "mailbox_not_found", "message": "找不到这个邮箱（或它不属于你）..." }

kind 有哪些

系统会自动分析每封邮件，一封信可能同时给好几项（比如验证码 + 验证链接），都在 message.items 里。

kind	含义
`code`	验证码（默认只要这个）
`link`	验证 / 登录 / 重置密码 / 授权 / 邀请 / 会议 / 下载链接
`password`	临时密码
`2fa`	两步验证密钥
`promo`	邀请码 / 优惠码 / 兑换码
`id`	像素ID / 订单号等资源标识（明确不是验证码）
`notice`	安全提醒类，只有说明没有可复制内容

限制

每把 Key 每分钟 300 次调用，超了返回 429 并带 Retry-After。
wait 最长 55 秒；全站同时最多 4 个请求在挂起等待。挤满时不会报错，而是立刻返回 waitSkipped: true，隔几秒重试即可。
这把 Key 不能删邮箱、不能改密码、不能发信。
邮件保留 30 天，之后自动清理。

HTTP 状态码

码	含义
`200`	成功（`found:false` 也是 200，表示「还没到」）
`201`	邮箱创建成功
`400`	参数不对，看 `message`
`401`	Key 缺失 / 无效 / 已停用
`404`	邮箱或邮件不存在，或不属于你
`405`	方法用错了（建邮箱和标已读要 POST）
`429`	超过频率限制

收信 API

把这段话发给别的 AI 对话，它就会用了

认证

端点

GET /api/v1/code 的参数

返回

kind 有哪些

限制

HTTP 状态码

`GET /api/v1/code` 的参数