API reference

POST /v1/verify

Verify one address.

Request

{
  "email": "mia@acme.com",
  "context": {
    "purpose": "signup",
    "sender_domain": "acme.com",
    "max_cost_usd": 0.002,
    "max_latency_ms": 800
  }
}

Only email is required. context.purpose is one of outbound, signup or list_hygiene. The two ceilings are hard: Sortance degrades to fewer providers and a wider confidence interval rather than exceeding a budget you stated.

Response fields

Every response also carries reason and reasons, from one closed vocabulary shared with /v1/check. The full table, with which codes end a request, is in the check reference.

POST /v1/check

The free checks alone: syntax, MX, Sortance’s disposable lists and your own domain and address rules, with the same reasons and the same email_type. No provider is called, so there is no verdict and no bounce_probability: this endpoint does not claim to know whether a mailbox exists. Same key, body limit and rate limit as /v1/verify; not counted against your monthly quota, and no trace is stored. The full explanation is in email check.

Request

{ "email": "test@mailinator.com" }

Response fields

/v1/domains

Your account’s own blocklist and allowlist of domains: GET, POST and DELETE on /v1/domains/blocklist and /v1/domains/allowlist, and POST /v1/domains/check. A block rule ends every check for the domain with domain_blocklisted; an allow rule sets Sortance’s disposable lists aside for it. Full reference in Blocklists.

/v1/addresses

Your account’s own blocklist and allowlist of single addresses. A blocked address ends every check with address_blocklisted (verdict invalid, no provider called, no cost); an allowed one has Sortance’s disposable lists and your domain blocks set aside, with address_allowlisted. An address rule beats any domain rule. Sortance keeps a keyed hash and a masked form, never the address, so a listing cannot give it back. Up to 10,000 address rules per account, blocklist and allowlist together. Any key can list and check; changing a list needs a member key. Not metered. Full reference in address rules.

POST /v1/decide

Verify the address, enrich it only if a rule needs it, apply your policy and return one decision (allow, allow_with_flow, review, challenge or deny) with the rule that made it. The verification is embedded unchanged as verification, email_type included, and rules read it as verification.email_type. The Email types switches on the dashboard’s Policy screen are rules in your default policy, so a “block free email” setting denies here and never changes a /v1/verify verdict. Metered like a verification. Full reference in decide and policies.

/v1/bulk

Bulk verification: upload a CSV, get it back with a verdict on every row. The four calls most integrations need are create, upload, start and download; the list guide walks through them, and the dashboard’s Bulk verify screen does the same with a drop zone. Each unique address counts as one verification against your monthly quota, cache hits included; duplicate rows share one answer. Bulk rows do not count against the per-minute rate limit. Viewer keys can list jobs and download results; everything else needs a member key.

A results file keeps your columns first, in order and unchanged, and appends these (the sortance_ prefix keeps them from colliding with yours):

Segments: deliverable is recommendation send, undeliverable is drop or a terminal reason, review is hold or challenge, and business is every row whose email_type is business. With a policy_slug the segments follow the decision instead: allow, deny, review. Running a policy can spend enrichment budget when its rules need a profile; the estimate’s max_cost_usd includes it. The uploaded file and the results are kept for 7 days, then deleted (trust).

POST /v1/screen

Screen a signup: is the address a typo, a placeholder, paired with a name that is not a real one, or at a domain that looks like a lookalike, a placeholder or a throwaway. The step after the domain’s MX resolves. Same auth, body limit and rate limit as /v1/verify; metered on its own allowance (10,000 screenings a month by default), not against verifications. The full explanation is in screening.

Request

{
  "email": "jhon.smtih@gmail.com",
  "name": "John Smith"
}

email is required, up to 320 characters, with the same rules as /v1/verify. name is optional, up to 200 characters after trimming; an empty name is treated as absent.

Response fields

POST /v1/outcome

Report what happened to a send. This is the only way your probabilities stop being everyone else’s averages.

{
  "trace_id": "vr_...",
  "outcome": "hard_bounce",
  "smtp_code": "550 5.1.1 User unknown"
}

• outcome — delivered, hard_bounce, soft_bounce, complaint or unknown.
• smtp_code — optional. Paste the whole bounce message if that is easier; Sortance reduces it to the basic and enhanced codes and discards the rest, including any recipient address in the text.
• The account is stamped from your key, never read from the body. One customer cannot write outcomes into another’s calibration.

GET /v1/traces and /v1/traces/:trace_id

The list gives you recent decisions across your organisation, from every key it holds. The single-trace form replays one: which providers were asked, what each returned, how long each took, what it cost, and the features the router decided on. Useful when a send went wrong and you want to know what Sortance actually knew at the time.

• ?bulk_job_id=bj_… narrows the list to the traces one bulk job wrote. Every trace carries bulk_job_id, null outside bulk jobs, and email_type, null on traces written before the field existed.
• ?key_id=key_… narrows the list to the rows one key of your organisation wrote. It works the same on GET /v1/screenings, the history of /v1/screen calls. A key id that is not in your organisation returns an empty page.
• A manual or service key below admin reads only the rows it wrote, whatever filter it asks for, and another key’s trace is a 404 to it. Dashboard keys and admin keys read the whole organisation. A leaked CI key therefore cannot expose every other key’s traffic.
• ?scope=owner is accepted and ignored for one release. It only selects the labelled row shape, where each row also carries account_id, api_key_id, key_name and key_origin, and policy_decision: { decision, rule_id, policy: { slug, version } } when /v1/decide wrote the trace, else null. Every read is organisation-wide already, so drop the parameter.

GET /v1/me

Who the presented key is and which organisation it acts for. Nothing in it is secret or personal.

{
  "account_id": "acct_…",
  "org": { "id": "org_…", "name": "Acme" },
  "key": { "id": "key_…", "role": "member", "origin": "manual" },
  "operator": false,
  "owner_user_id": "u_…"
}

account_id is your organisation’s account id, the same on every key the organisation holds. key.role is viewer, member or admin (see Teams); key.origin is auto (a dashboard key), manual (one you created) or service. owner_user_id is deprecated: it is the user who created the key and will be removed after one release. A personal organisation’s org.name reads “Personal org” until you rename it.

GET /v1/usage

Calls made, provider spend and quota remaining for the current period. Metered on the key’s organisation across every key it holds, including revoked ones. It also reports screenings used this month and the screening quota, which is a separate meter, as a screening object present on every response:

"screening": { "used": 412, "quota": 10000, "unmetered": false, "period": "utc_month" }

used is the screenings this calendar month (UTC), or null when the count could not be read, never a guessed zero. quota is the allowance, and unmetered is true when the quota is 0 or less. period is always utc_month.

A bulk object reports { jobs_this_month, rows_this_month }: bulk jobs started this month (UTC) and the verifications they metered. Those verifications are already inside the main count and quota; bulk rows and single calls share one allowance.

GET /health

Unauthenticated liveness check. Returns 200 when the worker is up.

Errors

Every non-2xx body is this shape, without exception:

{ "error": { "code": "quota_exceeded", "message": "...", "trace_id": "vr_..." } }