开发者文档API
Once Email API
面向自动化邮件测试的公开开发者文档：鉴权、配额、错误处理和安全使用原则。
文档已公开，API Key 创建和真实调用尚未面向公众开放。以下流程仅适用于已明确获得 API 访问授权且持有有效凭据的测试者。
鉴权
每次请求使用 Authorization: Bearer oe_live_…。密钥只在创建时显示一次；请存入密钥管理器，不要放进浏览器代码、日志或 Git 仓库。
Authorization: Bearer oe_live_your_key已获授权测试者的流程
- 仅在已明确获得 API 访问授权、并已持有最小必要权限的有效凭据时继续。凭据存入进程密钥设施；没有此访问资格时，只阅读文档和查看下载内容。 创建临时收件箱并保存返回的邮箱 ID。
- 让你的测试系统向该地址发送邮件。
- 轮询邮件列表；采用退避策略，不要高频空轮询。
- 读取目标邮件，完成断言后立即删除收件箱。
私有 Beta 接口
POST /v1/inboxesGET /v1/inboxes/{inboxId}/messagesGET /v1/inboxes/{inboxId}/messages/{uid}GET /v1/inboxes/{inboxId}/messages/{uid}/attachments/{cid}DELETE /v1/inboxes/{inboxId}状态码
400请求无效
401密钥缺失或无效
403方案或资源被拒绝
404资源不存在
413响应或附件超过上限
429达到频率或月度配额
503服务暂时失败
客户端可用状态
TypeScript、Python、Java、Go、.NET、PHP 和 Ruby 的开源预发布候选版已经提供。原生 CI 已在 Linux、macOS 和 Windows 通过；语言注册中心版本尚未发布。
计费状态
Developer 方案采用 Stripe 月度订阅和月度 API 配额，不提供储值充值。完成真实付款、退款等门禁前，Live 结账保持关闭。
使用边界
本 API 只用于你有权测试的系统。禁止垃圾邮件、绕过平台规则、账号滥用、监控他人通信或长期保存个人数据。邮箱正文和附件不进入账号历史。
API 正在进入生产准备阶段
公开文档和预发布包下载不代表获得 API 访问权限；API Key 创建和真实调用尚未公开开放。
API Demo
跨平台安全示例
面向你拥有或获授权的测试系统，可在 Windows、Linux、macOS 的 Node.js 20+ 运行。
node demos/api/authorized-workflow.mjs
ONCE_EMAIL_API_KEY <- process secret facility
create inbox -> list messages -> finally delete inbox完整使用指南
下载固定版本本地包
只测试你拥有或明确获授权的应用。Once Email 只接收邮件，不发送邮件，也不自动操作第三方注册。
文档和源码已公开；API 调用仍受控，SDK 与 Skill 是固定版本预发布下载，不是语言注册中心正式版本。 公开文档和预发布包下载不代表获得 API 访问权限；API Key 创建和真实调用尚未公开开放。
解压前先打开 SHA256SUMS 校验文件。
准确的本地起点
node demos/api/authorized-workflow.mjs从下载到第一次完整清理
- 确认目标属于你或已明确授权，并且只使用 local、test 或 staging 环境。
- 仅在已明确获得 API 访问授权、并已持有最小必要权限的有效凭据时继续。凭据存入进程密钥设施；没有此访问资格时，只阅读文档和查看下载内容。
- 下载、校验、解压，然后阅读 README.md 与 LOCAL-USAGE.md。
- 使用 Node.js 20+ 运行 Demo，再让获授权系统发送一封带唯一标记的邮件。
- 采用有界退避和统一截止时间轮询，只读取唯一匹配项。
- 无论成功失败都在 finally 删除收件箱，并把清理失败单独报告。
失败与恢复
必须区分 400、401、403、404、413、429 和 503；超时、歧义、提取、断言和清理也是不同失败。只在统一截止时间内重试，不能把依赖失败当成空收件箱。