inboxsink API

可由代码驱动的一次性收件箱，让你无需依赖真实邮箱即可测试注册流程。五个路由，统一以 https://inboxsink.com 为基址，收发 JSON。

真正改变局面的路由是 wait：它会阻塞到邮件抵达。没有它，端到端测试只能用 sleep 靠猜，一旦发送队列变慢就会变得不稳定。

免费 API 密钥

每月一千次调用，无需银行卡。足够接进你的测试套件，看它撑不撑得住。

创建免费账户 价格

之后，当你的测试开始被拒绝时：你自己的域名不会公开在任何地方，因此不会落入黑名单 — 每月 29 €。

JavaScript 客户端

零依赖的软件包，支持 Node 18 及以上版本。代码托管在 GitHub。

npm i inboxsink
import { InboxSink } from 'inboxsink';
const sink = new InboxSink(process.env.INBOXSINK_API_KEY);

const inbox = await sink.createInbox();
const code = await sink.waitForOtp(inbox.id);   // '204815'

当没有验证码到达时，waitForOtp 会抛出错误而不是返回 null：测试应当大声失败，而不是悄悄提交一个空字段。

身份认证

每次调用都带上 Authorization 请求头。密钥在控制台创建，以 ibsk_ 开头。

curl -H "Authorization: Bearer ibsk_…" \
  https://inboxsink.com/v1/domains

明文密钥只在创建时显示一次。之后只能看到它的前缀，我们保存的只有它的哈希值。

创建收件箱

POST /v1/inboxes

所有参数都是可选的：domain（默认从池中随机取一个域名）、prefix（默认随机）、ttl_seconds（60 秒到 30 天）。

curl -X POST https://inboxsink.com/v1/inboxes \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 900}'

→ 201
{ "id": "42", "address": "9f2c1a@mailhusk.com", "expires_at": "2026-09-01T15:12:00Z" }

通过 API 创建的收件箱是私有的：只有创建它的那把密钥才能读取。

等待一封邮件

GET /v1/inboxes/:id/wait

阻塞到有邮件抵达，然后立即响应。timeout 以毫秒计（默认 30 000，最大 120 000），since 用于只获取某个标识之后的邮件。

如果时限内没有邮件，返回没有正文的 204。这不是错误，而是对「什么都没来」的正常回答。

curl -H "Authorization: Bearer $KEY" \
  "https://inboxsink.com/v1/inboxes/42/wait?timeout=45000"

→ 200
{ "message": { "id": "913", "from": "no-reply@acme.com", "subject": "…",
               "otp": "204815", "link": "https://acme.com/confirm/9f3a" } }

otp 和 link 已经为你提取好了。只有当邮件确实在宣告一个验证码时才会上报（「验证码」「验证」「登录」等），发票金额或年份绝不会被误认成验证码。

列出邮件

GET /v1/inboxes/:id/messages

接受 since 和 limit（默认 50，最大 200）。返回摘要，不含邮件正文。

读取一封邮件

GET /v1/messages/:id

完整邮件：text、html、headers 以及附件列表。

删除收件箱

DELETE /v1/inboxes/:id

立即抹除收件箱及其邮件。返回 204。

错误

204无内容 — 对 wait 而言，是时限内没有邮件
400参数无效
401密钥缺失、未知或已吊销
403该收件箱属于另一把密钥
404收件箱或邮件不存在，或已过期
429调用过于频繁

限制与存活时间

公共池中的收件箱存活一小时；通过 API 创建的则遵循各自的 ttl_seconds，最长三十天。到期后收件箱及其邮件会被删除，事后没有任何归档可以取回。

超过十兆字节的邮件在接收时即被拒绝。未知域名下的地址会在 SMTP 会话中被拒绝，且不会产生退信。

这些收件箱无法发送邮件，这是刻意的：从一次性域名发出的邮件到不了任何地方。