开发者 API
创建密钥
在“管理 → 开发者”创建个人 API Key，并只授予业务需要的作用域。完整密钥只显示一次；丢失后撤销旧密钥并重新创建。
请求地址、鉴权格式和当前接口定义以应用内 OpenAPI 页面 https://to9.us/app/manage/developer/docs 为准。基本格式：
http
Authorization: Bearer <API_KEY>
Accept: application/json不要把真实密钥写进浏览器前端、公开仓库、日志、截图或工单。服务端程序通过环境变量或密钥管理服务注入。
作用域
API Key 可按资源限制邮件、邮箱、联系人、文件夹、标签、规则、签名、存储和附件等权限。读写操作还会继续执行当前用户的资源归属、组织角色、共享范围和配额检查。
邮箱共享是只读能力，不会因为调用 API 自动获得发信、改邮箱设置或创建客户端密码的权限。
创建和列出 API Key、修改密码、OAuth 绑定、找回邮箱、TOTP 和应用专用密码等凭据操作只允许真实浏览器会话，并拒绝管理员代入会话或 API Key 自身调用。
分页与筛选
列表接口可能使用 page、limit、搜索词、状态、邮箱、文件夹、标签或时间范围。客户端应遵守服务端返回的总数和边界，不能假设空页代表资源不存在。
邮件查询只返回调用者有权访问的邮箱；受限共享不会通过“全部邮箱”统计泄露未授权目录数量。
响应与错误
| 状态 | 含义 |
|---|---|
2xx | 请求成功 |
400 | 参数或业务状态不符合要求 |
401 | 凭据无效、过期或已撤销 |
403 | 作用域、资源权限或代入会话限制 |
404 | 资源不存在或当前身份不可见 |
409 | 唯一性、并发或当前状态冲突 |
429 | 请求、注册、登录或协议频率过高 |
5xx | 服务端或依赖暂时失败 |
安全敏感路径会把数据库、凭据和第三方详细错误留在受限服务端日志，并向客户端返回概括性错误；客户端仍不应依赖任意错误正文作为稳定协议，也不应把响应原样公开。排障时记录请求时间、路径、状态码和安全处理后的关联信息。
重试与幂等
客户端设置连接和读取超时。对网络错误和部分 5xx 使用带随机抖动的指数退避。发送邮件、创建订单、转让邮箱、兑换和删除等有副作用请求不能盲目重试；先查询最终状态或使用接口提供的幂等机制。
密钥轮换
- 创建权限相同或更小的新密钥。
- 更新应用配置并验证请求成功。
- 撤销旧密钥。
- 检查审计记录，确认没有旧密钥流量。