Automation BETA

Treat email verification as a task, not a mailbox.

Create a short-lived inbox, describe the sender or artifact you expect, and let SpotMail return the matched code or link with evidence. The inbox still expires on schedule.

Create a Project Key OpenAPI specification

Verification tracematched

01
Run created
checkout-smoke-1842
02
Inbox waiting
verify-7f2c@spotmail.app
03
Message matched
auth@sample.test
04
Artifact returned
code · 482 901
05
Inbox expires
24 hours maximum

One primitive, three jobs

Built for the moment email blocks the workflow.

CI and end-to-end tests

Create an isolated address per test, wait without fragile sleeps, and assert the exact verification artifact.

Idempotent create
Long-poll claim
Stable request IDs

AI agents

Freeze one human-approved verification Profile into each Key, then let the agent invoke it without rewriting the sender or result policy.

Locked Profile
Capability preflight
Run-scoped token

Product operations

Route accepted mail to signed webhooks, replay a failed delivery, and inspect current usage from the account.

Signed webhooks
Delivery history
Usage ledger

The contract

Six operations cover the full verification lifecycle.

Project Keys create and inspect work. A run-scoped token claims, completes, or cancels one task. No operation sends email.

01GET
/api/verification-runs/usage
Confirm capability and current headroom
02POST
/api/verification-runs
Create or replay one task
03GET
/api/verification-runs/{id}
Inspect task state
04POST
/api/verification-runs/{id}/claim
Wait for a matched artifact
05POST
/api/verification-runs/{id}/complete
Record the caller verdict
06DELETE
/api/verification-runs/{id}
End work early

TypeScript SDK

The happy path stays small.

Preflight catches the wrong Key, changed Profile, or a credential that expires before the Run can finish. The same fingerprint stays on the Run and Activity record.

BETA package contract · REST remains the source of truth

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 boundaries

Useful now, without pretending to be permanent email.

Receive only

SpotMail does not send mail, manage threads, or become an agent identity.

Explicit capacity

6 creates per minute, 50 Verification Runs per UTC day per account, and a configurable daily budget for each Key.

Content-free request telemetry

Seven-day transport records keep request ID, operation, normalized client, status, duration, and stable error—never the mail body or credential.

Short-lived by default

Run inboxes expire within 24 hours. Idempotency tombstones outlive content only long enough to make retries safe.

Start from the source

The inbox is infrastructure. The verification result is the product.

Start with the REST contract or create a Project Key and run the first task from your test suite or agent.

Create a Project Key