自动化 BETA

把邮件验证当成一项任务，而不是一个邮箱。

创建短生命周期收件箱，描述期待的发件人或验证结果，SpotMail 会返回匹配到的验证码或链接及其证据；邮箱仍会按时到期。

创建 Project Key 查看 OpenAPI

验证链路已匹配

01
任务已创建
checkout-smoke-1842
02
等待收件
verify-7f2c@spotmail.app
03
匹配邮件
auth@sample.test
04
返回结果
验证码 · 482 901
05
邮箱到期
最长 24 小时

一个原语，三类任务

专门处理“邮件验证卡住工作流”的时刻。

CI 与端到端测试

为每条测试创建隔离地址，不再依赖脆弱的固定等待，并直接断言真实验证结果。

幂等创建
长轮询领取
稳定 Request ID

AI Agent

每把 Key 只冻结一项由人批准的验证 Profile；Agent 只能引用它，不能改写发件人或结果策略。

固定 Profile
能力预检
任务级令牌

产品运维

通过签名 Webhook 接收事件、重放失败投递，并从账号侧查看当前用量。

签名 Webhook
投递历史
用量账本

接口契约

六个操作覆盖完整验证生命周期。

Project Key 负责创建与查看任务；任务级令牌只能领取、完成或取消这一项任务。所有接口都只收不发。

01GET
/api/verification-runs/usage
确认能力与当前余量
02POST
/api/verification-runs
创建或幂等恢复任务
03GET
/api/verification-runs/{id}
查看任务状态
04POST
/api/verification-runs/{id}/claim
等待匹配的验证结果
05POST
/api/verification-runs/{id}/complete
记录调用方结论
06DELETE
/api/verification-runs/{id}
提前结束任务

TypeScript SDK

正常路径应该足够短。

Preflight 会在分配资源前发现拿错 Key、Profile 漂移或凭证寿命不足；同一指纹会保留到 Run 与 Activity。

BETA 包契约 · REST 仍是事实来源

verification-run.ts

import { SpotMailClient } from '@spotmail/sdk';

const spotmail = new SpotMailClient({
  apiKey: process.env.SPOTMAIL_API_KEY!,
  environment: 'staging',
});

await spotmail.verificationRuns.preflight({
  profile: 'signup-code',
  contractFingerprint: process.env.SPOTMAIL_PROFILE_FINGERPRINT,
});

const run = await spotmail.verificationRuns.create(
  {
    profile: 'signup-code',
    context: { clientReference: 'signup-e2e-1842' },
  },
  { idempotencyKey: 'signup-e2e-1842' },
);

const claim = await run.wait({ maxWaitSeconds: 120 });
if (claim.result?.artifact.kind === 'code') {
  console.log(claim.result.artifact.value);
}

BETA 边界