Source: https://once-email.com/zh_cn/api 开发者文档 开发者文档 API # Once Email API 面向自动化邮件测试的公开开发者文档：鉴权、配额、错误处理和安全使用原则。 文档已公开，API Key 创建和真实调用尚未面向公众开放。以下流程仅适用于已明确获得 API 访问授权且持有有效凭据的测试者。 鉴权 每次请求使用 Authorization: Bearer oe\_live\_…。密钥只在创建时显示一次；请存入密钥管理器，不要放进浏览器代码、日志或 Git 仓库。 ``` Authorization: Bearer oe_live_your_key ``` 已获授权测试者的流程 1. 仅在已明确获得 API 访问授权、并已持有最小必要权限的有效凭据时继续。凭据存入进程密钥设施；没有此访问资格时，只阅读文档和查看下载内容。 创建临时收件箱并保存返回的邮箱 ID。 2. 让你的测试系统向该地址发送邮件。 3. 轮询邮件列表；采用退避策略，不要高频空轮询。 4. 读取目标邮件，完成断言后立即删除收件箱。 ## 私有 Beta 接口 ` POST /v1/inboxes `` GET /v1/inboxes/{inboxId}/messages `` GET /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 创建和真实调用尚未公开开放。 [查看 SDK]() 查看价格 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 ``` [查看完整 Demo]() 完整使用指南 ## 下载固定版本本地包 只测试你拥有或明确获授权的应用。Once Email 只接收邮件，不发送邮件，也不自动操作第三方注册。 文档和源码已公开；API 调用仍受控，SDK 与 Skill 是固定版本预发布下载，不是语言注册中心正式版本。 公开文档和预发布包下载不代表获得 API 访问权限；API Key 创建和真实调用尚未公开开放。 解压前先打开 SHA256SUMS 校验文件。 [下载本地包]() [SHA256SUMS]() 准确的本地起点 ``` node demos/api/authorized-workflow.mjs ``` ## 从下载到第一次完整清理 1. 确认目标属于你或已明确授权，并且只使用 local、test 或 staging 环境。 2. 仅在已明确获得 API 访问授权、并已持有最小必要权限的有效凭据时继续。凭据存入进程密钥设施；没有此访问资格时，只阅读文档和查看下载内容。 3. 下载、校验、解压，然后阅读 README.md 与 LOCAL-USAGE.md。 4. 使用 Node.js 20+ 运行 Demo，再让获授权系统发送一封带唯一标记的邮件。 5. 采用有界退避和统一截止时间轮询，只读取唯一匹配项。 6. 无论成功失败都在 finally 删除收件箱，并把清理失败单独报告。 ## 失败与恢复 必须区分 400、401、403、404、413、429 和 503；超时、歧义、提取、断言和清理也是不同失败。只在统一截止时间内重试，不能把依赖失败当成空收件箱。 [查看公开源码]() [阅读实战指南]()