# info.summary
Short-lived, receive-only email verification for automation.

# info.description
Server-to-server BETA API. Inspect shared account headroom, create one policy-bound temporary address, wait for a deterministic code or HTTPS action link, then complete or cancel the task. Email content is untrusted and is never returned by this surface. Browser CORS is not supported.

# tags[].description
Task-scoped verification primitives for CI and user-authorized agents.

# paths./api/verification-runs.post.summary
Create one policy-bound verification task

# paths./api/verification-runs.post.description
Keep the Project Key in a trusted server or secret store. The returned run token is scoped to this task and expires with it.

# paths./api/verification-runs.post.parameters[].description
Explicit project namespace. It must match the immutable Project Key binding.

# paths./api/verification-runs.post.parameters[].description
Explicit execution environment. It must match the immutable Project Key binding.

# paths./api/verification-runs.post.parameters[].description
Stable, unpredictable identifier for one logical task.

# paths./api/verification-runs.post.responses.200.description
Idempotent replay of the original creation.

# paths./api/verification-runs.post.responses.200.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs.post.responses.201.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs.post.responses.400.description
Missing environment handshake, invalid idempotency key, or invalid task policy.

# paths./api/verification-runs.post.responses.400.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs.post.responses.401.description
Missing, invalid, expired, or revoked key.

# paths./api/verification-runs.post.responses.401.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs.post.responses.403.description
Project Key permission, policy, or active resource allowance is insufficient.

# paths./api/verification-runs.post.responses.403.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs.post.responses.409.description
The environment does not match the Project Key, its remaining lifetime cannot cover the Run, or the idempotency key was used with another policy.

# paths./api/verification-runs.post.responses.409.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs.post.responses.429.description
Project request or creation limit reached.

# paths./api/verification-runs.post.responses.429.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs.post.responses.429.headers.Retry-After.description
Whole seconds until the caller should retry.

# paths./api/verification-runs.post.responses.500.description
Unexpected server failure. Safe to retry.

# paths./api/verification-runs.post.responses.500.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs.post.responses.503.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/usage.get.description
Returns credential lifetime, effective capability, account-global creation allowances, the calling Project Key daily Verification Run budget, and observational accepted-mail usage for only that Key. It does not consume either allowance.

# paths./api/verification-runs/usage.get.parameters[].description
Explicit project namespace. It must match the immutable Project Key binding.

# paths./api/verification-runs/usage.get.parameters[].description
Explicit execution environment. It must match the immutable Project Key binding.

# paths./api/verification-runs/usage.get.responses.200.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/usage.get.responses.400.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/usage.get.responses.401.description
Missing, invalid, expired, or revoked key.

# paths./api/verification-runs/usage.get.responses.401.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/usage.get.responses.403.description
Project Key lacks verification:run permission.

# paths./api/verification-runs/usage.get.responses.403.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/usage.get.responses.409.description
The requested environment does not match the Project Key.

# paths./api/verification-runs/usage.get.responses.409.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/usage.get.responses.429.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/usage.get.responses.429.headers.Retry-After.description
Whole seconds until the caller should retry.

# paths./api/verification-runs/usage.get.responses.500.description
Unexpected server failure. Safe to retry.

# paths./api/verification-runs/usage.get.responses.500.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.get.responses.200.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.get.responses.401.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.get.responses.404.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.get.responses.429.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.get.responses.429.headers.Retry-After.description
Whole seconds until the caller should retry.

# paths./api/verification-runs/{runId}.get.responses.500.description
Unexpected server failure. Safe to retry.

# paths./api/verification-runs/{runId}.get.responses.500.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.delete.summary
Cancel the task and destroy retained content

# paths./api/verification-runs/{runId}.delete.responses.200.description
Current terminal snapshot; an active task is transitioned to cancelled.

# paths./api/verification-runs/{runId}.delete.responses.200.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.delete.responses.401.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.delete.responses.404.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.delete.responses.429.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}.delete.responses.429.headers.Retry-After.description
Whole seconds until the caller should retry.

# paths./api/verification-runs/{runId}.delete.responses.500.description
Unexpected server failure. Safe to retry.

# paths./api/verification-runs/{runId}.delete.responses.500.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/claim.post.summary
Wait for the first policy-matching result

# paths./api/verification-runs/{runId}/claim.post.description
Returns immediately for a terminal task. A timeout is a successful response whose status remains waiting. Only one claim may wait on a task at a time.

# paths./api/verification-runs/{runId}/claim.post.responses.200.description
Matched, terminal, or explicitly timed out.

# paths./api/verification-runs/{runId}/claim.post.responses.200.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/claim.post.responses.400.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/claim.post.responses.401.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/claim.post.responses.404.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/claim.post.responses.409.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/claim.post.responses.409.headers.Retry-After.description
Whole seconds until the caller should retry.

# paths./api/verification-runs/{runId}/claim.post.responses.429.description
Authentication or long-poll limit reached.

# paths./api/verification-runs/{runId}/claim.post.responses.429.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/claim.post.responses.429.headers.Retry-After.description
Whole seconds until the caller should retry.

# paths./api/verification-runs/{runId}/claim.post.responses.500.description
Unexpected server failure. Safe to retry.

# paths./api/verification-runs/{runId}/claim.post.responses.500.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/complete.post.summary
Report the caller-observed downstream outcome and destroy content

# paths./api/verification-runs/{runId}/complete.post.responses.200.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/complete.post.responses.400.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/complete.post.responses.401.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/complete.post.responses.404.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/complete.post.responses.409.description
Task is still waiting or is already terminal and cannot be completed.

# paths./api/verification-runs/{runId}/complete.post.responses.409.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/complete.post.responses.429.headers.X-Request-ID.description
Identifier for support and log correlation.

# paths./api/verification-runs/{runId}/complete.post.responses.429.headers.Retry-After.description
Whole seconds until the caller should retry.

# paths./api/verification-runs/{runId}/complete.post.responses.500.description
Unexpected server failure. Safe to retry.

# paths./api/verification-runs/{runId}/complete.post.responses.500.headers.X-Request-ID.description
Identifier for support and log correlation.

# components.securitySchemes.projectKey.description
Revocable Project Key with verification:run permission. Never expose it to a model or browser bundle.

# components.securitySchemes.runToken.description
Short-lived capability returned by task creation. It cannot read message bodies or another task.

# components.schemas.ProjectVerificationUsage.properties.access.description
Current commercial and product boundary for the no-checkout Automation BETA.

# components.schemas.ProjectVerificationUsage.properties.access.properties.primaryValueUnit.description
The product outcome SpotMail is validating before introducing paid capacity.

# components.schemas.ProjectVerificationUsage.properties.scope.properties.project.description
Server-derived Project Key namespace. It is null only for legacy keys.

# components.schemas.ProjectVerificationUsage.properties.credential.description
Authenticated lifetime state for deciding whether the Project Key can remain valid through a complete Run.

# components.schemas.ProjectVerificationUsage.properties.credential.properties.expiresAt.description
Absolute Project Key expiry, or null only for a non-expiring legacy credential.

# components.schemas.ProjectVerificationUsage.properties.credential.properties.remainingSeconds.description
Whole seconds remaining at observedAt, or null for a non-expiring legacy credential.

# components.schemas.ProjectVerificationUsage.properties.credential.properties.runLifetimeBufferSeconds.description
Additional credential lifetime required beyond the full Run TTL.

# components.schemas.ProjectVerificationUsage.properties.capability.description
Authenticated, allocation-free manifest for confirming the effective Project Key policy before creating a Run.

# components.schemas.ProjectVerificationUsage.properties.capability.properties.profile.oneOf[].properties.contractFingerprint.description
Stable SHA-256 fingerprint over the versioned, canonical Profile contract.

# components.schemas.CreateVerificationRunRequest.description
Use a locked owner-defined Profile for Agent calls, or provide the legacy inline task policy.

# components.schemas.ProfileVerificationRunRequest.properties.profile.description
Exact locked Verification Profile name stored in the Project Key.

# components.schemas.InlineVerificationRunRequest.properties.approvalMode.description
Manual runs withhold a matched artifact until the signed-in account owner approves its release.

# components.schemas.InlineVerificationRunRequest.properties.expectedSenderDomain.description
ASCII DNS hostname. IP literals and IDN punycode are rejected.

# components.schemas.InlineVerificationRunRequest.properties.expectedCodeLength.description
Optional exact normalized code length. Numeric codes support 4–8; mixed alphanumeric codes support 4–10.

# components.schemas.InlineVerificationRunRequest.properties.expectedCodeFormat.description
Optional code format. Alphanumeric requires at least one ASCII letter and one digit.

# components.schemas.InlineVerificationRunRequest.properties.expectedActionHost.description
Exact ASCII HTTPS hostname. IP literals and IDN punycode are rejected.

# components.schemas.InlineVerificationRunRequest.properties.expectedActionPathPrefix.description
Optional exact or segment-safe HTTPS pathname prefix on expectedActionHost. Query and fragment are never matched.

# components.schemas.VerificationRunVerdict.description
Machine decision derived from the lifecycle: waiting or awaiting_approval is pending; matched or completed is passed; exhausted is failed; expired is timed_out; cancelled remains cancelled.

# components.schemas.VerificationRunDiagnostics.description
Content-free evidence for explaining a pending or terminal verdict. Rejection reason counts are mutually exclusive and sum to rejectedMessages.

# components.schemas.VerificationRunDiagnostics.properties.matchLatencyMs.description
Elapsed milliseconds, or null before a policy-matching message arrives.

# components.schemas.VerificationRunContextInput.description
Caller-controlled correlation tokens. Do not put secrets, personal data, email content, or instructions here.

# components.schemas.VerificationRunContext.properties.project.description
Server-derived Project Key namespace. Callers cannot submit or override it.

# components.schemas.VerificationRunContext.properties.environment.description
Server-derived Project Key environment. It is null only for session-created or legacy runs.

# components.schemas.VerificationRunContext.properties.profile.description
Server-confirmed locked Verification Profile. It is null for inline-policy runs.

# components.schemas.VerificationRunContext.properties.profileFingerprint.description
Server-derived immutable fingerprint of the exact locked Profile contract used by this run. It is null for inline-policy and legacy runs.

# components.schemas.VerificationRunDataLifecycle.properties.contentState.description
Whether task-bound address, email content, extracted result, and content-bearing webhook payloads remain retrievable by SpotMail.

# components.schemas.VerificationRunDataLifecycle.properties.purgedAt.description
Unix epoch milliseconds, or null when the event has not occurred.

# components.schemas.VerificationRunDataLifecycle.properties.tombstoneExpiresAt.description
When the content-free task tombstone is eligible for deletion.

# components.schemas.VerificationRunDataLifecycle.description
Authoritative SpotMail lifecycle receipt. It is not a cryptographic attestation and does not cover data already sent to external systems.

# components.schemas.VerificationRunSnapshot.properties.extractorVersion.description
Immutable deterministic artifact rule set selected when the run was created.

# components.schemas.VerificationRunSnapshot.properties.matchedAt.description
Unix epoch milliseconds, or null when the event has not occurred.

# components.schemas.VerificationRunSnapshot.properties.completedAt.description
Unix epoch milliseconds, or null when the event has not occurred.

# components.schemas.VerificationRunSnapshot.properties.cancelledAt.description
Unix epoch milliseconds, or null when the event has not occurred.

# components.schemas.CreateVerificationRunResponse.properties.extractorVersion.description
Immutable deterministic artifact rule set selected when the run was created.

# components.schemas.CreateVerificationRunResponse.properties.matchedAt.description
Unix epoch milliseconds, or null when the event has not occurred.

# components.schemas.CreateVerificationRunResponse.properties.completedAt.description
Unix epoch milliseconds, or null when the event has not occurred.

# components.schemas.CreateVerificationRunResponse.properties.cancelledAt.description
Unix epoch milliseconds, or null when the event has not occurred.

# components.schemas.CreateVerificationRunResponse.properties.runToken.description
Store outside model context and logs. Use only for this run.

# components.schemas.VerificationRunClaim.properties.matchedAt.description
Unix epoch milliseconds, or null when the event has not occurred.

# components.schemas.DownstreamOutcome.description
Caller-reported destination outcome. It is not independently observed or verified by SpotMail.