Key concepts

Before you dive into request/response tables, these ideas shape how truval.dev fits agent and product workflows.

Provisioning keys vs standard keys

truval.dev uses two kinds of secrets:

Kind	Prefix	Purpose
Provisioning key	sk_mgmt_...	Call the Management API only: create and revoke standard keys, read usage, open the billing portal. Created once in the dashboard; treat like infrastructure credentials.
Standard key	sk_live_... or sk_test_...	Call Email verify (POST /v1/email/verify and related routes). This is what your app or agent uses day to day to verify addresses.

Typical pattern: a human creates a single provisioning key and stores it in the environment. At runtime, an agent (or service) uses it to self-provision a standard key, caches that key, and verifies emails with the standard key. You never use the provisioning key on the verify endpoint.

Details: Management API, Agent bootstrap.

Confidence ladder

The API returns a numeric confidence field (0–1). It is an ordinal summary of how decisive the pipeline was under truval.dev’s rules — not a calibrated probability that the mailbox exists.

Use status, failed_check, mx_found, and smtp_blocked together with confidence. For example, major providers often return smtp_blocked: true with confidence around 0.75; that is expected and usually acceptable, not a failed check.

The full band-by-band reference lives on Email verify — confidence ladder. For agent policy (what to accept, reject, or ask the user), start with the Agent decision guide.

Read next

• Quick start — verify an address in one request
• Email verify — full API reference
• Reference — Security — HMAC webhooks, SSRF-safe callbacks, data residency