Authentication
Every verification request is authenticated with an API key sent as a bearer token.
Authorization: Bearer pm_live_your_key
Key format
Keys are prefixed so you can tell them apart at a glance:
pm_live_...: production keys, billed against your wallet.pm_test_...: sandbox keys for integration work.
The raw key is shown once, at creation time. Only its hash is stored, so store it somewhere safe. If you lose it, revoke it and create a new one.
Sandbox test mode
A pm_test_ key runs a deterministic sandbox: it never dials SMTP, never touches a real mailbox, and reserves nothing from your wallet, so you can wire up an integration without spending credits. The outcome is chosen from the address local part, so your test suite can assert against a stable contract:
valid@...returns a deliverable result with a high score.invalid@...returns an undeliverable result.catchall@...,disposable@..., androle@...return the matching risky result.- Any other local part returns a deliverable result with a moderate score.
The response shape is identical to a live verification, so the same code path handles both. Switch to a pm_live_ key to run the real pipeline.
Scopes and checks
A key carries granular scopes and the set of checks it is allowed to run (for example SMTP is available only on the plans that include it). The rate limit is plan-driven and not editable per key.
Billing
Verification is billed from your token wallet, not per request. A call reserves the estimated cost up front and commits or refunds it once the job finishes, so you only pay for the checks that actually ran. When the wallet is empty the API returns 402 Payment Required, distinct from a 403 scope error, so your SDK can tell "top up" from "missing permission".