The whole API is one POST
Sortance is a router, not a dashboard. You send an address, it decides which verification providers to ask, and it returns one calibrated bounce probability with the evidence behind it. Everything else in these docs is detail on that one call.
Quickstart
Sign in, get a key, make your first verified call. Five minutes, one curl command, no SDK.
API reference
Every endpoint, every field of the response, every error code, and what each one means.
Going to production
Rate limits, quotas, the fail-open contract, caching semantics and what degraded means.
Verify a list
Upload a CSV and get it back with a verdict per row, from the dashboard or four API calls. Or run the loop from your side.
MCP server
Connect Claude, Cursor or any MCP client with your API key. Verify, enrich, screen and check addresses, and set your rules in plain English.
Screening
POST /v1/screen: the step after the MX resolves. Catch typo'd addresses and fake names at signup; allow or review, never a block.
Domain validation
How a domain is judged: the free gate and its three-tier disposable lists, the in-process Sortance check first in the pool, and Jev for look-alike, typo, placeholder and throwaway domains.
Email check and reasons
POST /v1/check: the free syntax, MX and disposable checks alone, the closed reason vocabulary /v1/verify shares, email_type (business, free, role, disposable, relay), and where each route of the old email-check service moved.
Blocklists
Your account's own blocklist and allowlist of domains and of single addresses. A blocked domain or address fails every check for free; an allowed one is exempt from the disposable lists.
Teams
Organisations, roles and invitations: share keys, configuration and quota with your team, and what each API key role may call.
JavaScript SDK
sortance.js: one dependency-free file. isValidEmail, isDisposableEmail, getEmailProvider and isBusinessEmail as drop-in functions, plus your domain and address blocklists and bulk list verification.
The shape of it
One authenticated POST carrying an address. The response is a probability rather than a label, because a label is what every provider already gives you and it is not enough to make a send decision with.
curl -X POST https://api.sortance.com/v1/verify \
-H "Authorization: Bearer $SORTANCE_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"mia@acme.com"}'The full field list is in the API reference. The three fields you cannot get from a single provider are bounce_probability with its confidence_interval, disagreement, and actor_class.
Endpoints
| Method | Path | Does |
|---|---|---|
POST | /v1/verify | Verify one address. The product. |
POST | /v1/check | The free checks alone: syntax, MX, disposable domains and your own rules, with a reason and the email type. No provider, no quota. |
POST | /v1/screen | Screen a signup: a typo’d address, a placeholder, or a name that is not a real one. Its own monthly allowance. |
POST | /v1/outcome | Report what actually happened to a send. This is what moves your numbers from a prior to a fitted curve. |
GET | /v1/traces | List recent decisions on your account. |
GET | /v1/traces/:trace_id | Replay one decision, including which providers answered. |
GET | /v1/usage | Calls made, spend, and quota remaining, for verifications and screenings. |
GET POST DELETE | /v1/domains/blocklist, /v1/domains/allowlist | Your account’s own domain rules, plus POST /v1/domains/check. |
GET POST DELETE | /v1/addresses/blocklist, /v1/addresses/allowlist | Your account’s own address rules, kept as a hash and a masked form, plus POST /v1/addresses/check. |
POST PUT GET | /v1/bulk/jobs | Bulk verification: upload a CSV, start it, download it back with a verdict on every row. |
GET | /health | Unauthenticated liveness check. |
The identity router
A second set of endpoints sits on the same key. Where /v1/verify answers “will this bounce”, /v1/decide answers “should this one get in, under the rules I wrote” — verifying the address, buying an enrichment profile only when a rule needs one, and returning the decision with the rule that made it.
Decide
POST /v1/decide: verify, enrich only if a rule needs it, apply your policy, return one decision with its reasons.
Policies
The rule schema, the closed field vocabulary, the Email types switches, compile from English (“block all non business emails”), replay against your traffic, activate.
Lists
Named allow, deny and neutral sets of domains, patterns and hashed addresses that rules can reference.
Enrich
POST /v1/enrich and the EnrichmentProfile: every field, the normalized vocabularies, coverage and receipts.
ICP
Write an ideal-customer rubric, score it deterministically, and read the coverage next to every score.
Experiments
Shadow and enforced experiments over policy versions, and the report that refuses to guess below its minimum sample.
Events
POST /v1/events: tell Sortance what a signup went on to do. Free, unmetered, and the input every report runs on.
Stripe
Connect Stripe as an outcome source: the permissions to grant, the webhook, and metadata.sortance_trace_id.
What is deliberately not here
No hygiene score and no headline accuracy number; the reasons are on limitations. Lists are the one place Sortance takes a file: bulk verification keeps the CSV and its results for 7 days, then deletes them. If you would rather the list never leave your systems, the list guide also has the loop.