API reference

Authentication

Every request carries an API key as a bearer token. Create and revoke keys from the dashboard; a key is shown once at creation and stored hashed.

Authorization: Bearer sk_live_…
Content-Type: application/json

There are two kinds of keys. Secret keys authenticate servers and unlock the full API. Publishable pk_ keys are safe in browser page source: they can only run single lookups through the four browser endpoints, POST /api/v1/email/public, /api/v1/phone/public, /api/v1/ip/public and /api/v1/address/public, and only from the domains they are locked to. Both are managed on the dashboard's API keys page.

Billing

You pay for answers, not attempts. One balance covers every endpoint, and anything you paid to check once is free to check again for a week.

Responses include meta.credits_used, meta.credits_remaining, and meta.cache_hit so your own accounting never drifts from ours; an IP answer also carries meta.ip_lookups_prepaid and an email answer meta.fair_use_billed.

IP lookups are billed in blocks of five: the answered IP lookup that opens a block reports credits_used 1 and leaves four prepaid on the account, and the next four report 0. Undeliverable email verdicts that needed a mailbox check are free up to a fair-use allowance of 500 in any 30 days, or the number of deliverable and risky email answers billed in those 30 days when that is more. Past the allowance each one costs 1 credit and its meta.fair_use_billed is true. Verdicts settled without a mailbox check (bad syntax, no working mail server, a username the provider never allows) and repeats are always free and never counted.

Errors & rate limits

Failures return { success: false, error: { code, message } } with a stable code to branch on. Every key may make 5 requests per second (50 for IP and phone endpoints, each in its own bucket); a batch or bulk call counts as one request. A key created with a default country supplies it to phone lookups that name none. A key's own scopes, daily cap and address allowlist answer KEY_SCOPE_DENIED, KEY_SPEND_CAP_REACHED and KEY_IP_NOT_ALLOWED before anything is billed; see key controls. The daily cap also stops a batch part-way: when it runs out mid-list the call keeps the items already paid for and reports meta.stopped_reason: "key_spend_cap" with a 200.

Each code has its own page under error codes, and every verdict reason under verdict reasons.

Every response carries an X-Request-Id header, repeated as meta.request_id on successful lookups and error.request_id on typed errors. Quote it when you write to support: it matches the id on every log line the request produced.

GET /api/v1/account

Account

Your current credit balance and monthly grant — useful for dashboards and pre-flight checks before a big run.

POST /api/v1/email

Email verification

Syntax, live DNS, open domain lists, domain auth records, and a mailbox-level SMTP check — the full answer in every lookup, at one credit for a deliverable or risky verdict whose mailbox check was definite. An uncertain (unverified) answer is free, and an undeliverable one is free within fair use. No mail is ever sent.

$ curl https://spaw.co/api/v1/email \
    -H "Authorization: Bearer sk_live_…" \
    -d '{"email": "[email protected]"}'

Request

With a callback pair the response also carries meta.settling: true when a re-check was scheduled, false when the answer was already final. The callback body is { event: "email.settled", request_id, settled, attempt, data, meta } with the same data fields as this endpoint; settled is false when the last re-check still could not say. An unverified answer is free and leaves nothing to repeat, so a re-check bills 1 credit when it confirms the mailbox and nothing while it still cannot say. One your balance cannot pay for is not run: the last callback then has settled false, data null and meta.stopped_reason "insufficient_credits".

Response fields · data.*

Every response also carries a sources array naming the dataset and version behind each field.

Suppression list

An undeliverable verdict adds the address, in normalized form, to your account's suppression list. Batch, bulk, and monitor runs serve suppressed addresses from the stored verdict — free, marked meta.suppressed: true — instead of re-verifying them. A single lookup always re-verifies, and a verdict other than undeliverable removes only an entry an undeliverable verdict added. An import and a complaint stay until you remove them, and a bounce you reported leaves when you report a delivery to that address; a complaint about an address you imported is recorded on that entry, which stays an import. Imports and complaints never go stale, though an import serves a verdict it kept from before you imported it only for 90 days after the entry was last renewed; any other entry older than 90 days is re-verified instead of trusted.

Manage it directly: GET /api/v1/email/suppressions lists entries, POST /api/v1/email/suppressions imports up to 10,000 known-bad addresses per request — your provider's bounce export, honored from day one at no credit cost, answered with reason "suppressed" — and DELETE /api/v1/email/suppressions/{id} removes one.

Browser lookups with a publishable key

POST /api/v1/email/public takes { key, email } with a publishable key, checked against the browser's Origin header and the key's allowed domains. It powers the form helper, bills the key's owner under the normal rules, and returns { success, data } without a meta block, so page visitors never see your balance. POST /api/v1/phone/public does the same for phone fields with { key, phone, country }, never with the live carrier check. Server-side requests should use a secret key and the standard endpoints instead. Because the key sits in page source, give it a daily credit cap in the dashboard: once the cap is spent the endpoint answers 429 KEY_SPEND_CAP_REACHED until the next day, and your balance is safe from a scripted crowd. For forms open to the public, add a Cloudflare Turnstile pair to the key as well: the endpoint then requires a confirmed turnstile_token with every lookup and answers 403 TURNSTILE_FAILED without one, before any credit is spent. The form helper handles the token when the script tag carries data-turnstile-site-key.

Test addresses

Six fixed addresses on the reserved spaw.test domain always answer the same canonical result, cost no credits, touch no DNS or mail server, and never appear in your history or suppression list — the way payment providers publish test card numbers. Use them in integration tests and staging pipelines; a plus-tag ([email protected]) works too. They answer on every endpoint, including batch, bulk, and the browser endpoint.

POST /api/v1/email/batch

Email batch

Up to 50 addresses in one synchronous call, each under the exact single-lookup billing rules. Their mailbox probes are sent to the verification provider concurrently, so a full batch takes about as long as a handful of single lookups. data.results[] mirrors the single response per address. Running out of credits mid-batch returns the paid partial results with meta.stopped_reason: "insufficient_credits" instead of discarding billed work; only a batch whose first lookup is refused returns the typed 402. A key's own daily credit cap stops a batch the same way, with meta.stopped_reason: "key_spend_cap"; if the account runs out of credits in the same batch, that stop is reported instead, because a spent balance is money and a cap is only your own policy. A batch that begins with the cap already spent still answers 429 KEY_SPEND_CAP_REACHED and runs nothing. Each item's meta carries credits_used, cache_hit, and suppressed.

GET /api/v1/email/domain/{domain}

Domain intelligence

The domain-level signals of an email lookup — MX, provider, SPF and DMARC, the disposable and free-provider lists — answered once for a whole domain. One credit when the domain accepts mail; an invalid or dead domain is free, and repeats within 7 days are free.

$ curl https://spaw.co/api/v1/email/domain/acme.com \
    -H "Authorization: Bearer sk_live_…"

Response fields · data.*

POST /api/v1/email/bulk

Bulk jobs & webhooks

Queue up to 100,000 addresses in one job. Creation answers 202 with the job's id and status; poll GET /api/v1/email/bulk/{id} for progress, then download the result CSV from GET /api/v1/email/bulk/{id}/results. Jobs and their files are kept for 30 days.

The result file starts with the input's own columns (for an API list, a single email column; for a dashboard upload, every column of the file) followed by verified_email and the verdict fields, one row per input row in the original order. Add ?variant=deliverable (or risky, undeliverable) to download only those rows. Rows repeating an address already in the list are verified once and counted in duplicate_count. Addresses at a domain already known to be catch-all, and addresses your account reported delivered recently, answer without a probe.

POST /api/v1/email/bulk/{id}/cancel stops a run: a queued job is cancelled on the spot, a running one at its next checkpoint. Rows already verified stay billed and downloadable — as do the rows a run that failed part-way had already written — and the webhook fires with status cancelled just as it does for completed and failed.

Verifying the webhook signature

When the job finishes we POST a JSON summary to your webhook. X-Spaw-Signature-V2 carries two elements, t={unix seconds},v2={hex}: the hex is the HMAC-SHA256 of v2:{t}:{raw body}, keyed with the secret from job creation. Check the timestamp as well as the digest — a signature over the body alone never goes stale, so a captured delivery could be posted back at you a year later and still verify.

$elements = [];

foreach (explode(',', (string) $request->header('X-Spaw-Signature-V2')) as $element) {
    $pair = explode('=', trim($element), 2);

    if (count($pair) === 2) {
        $elements[$pair[0]] = $pair[1];
    }
}

$timestamp = $elements['t'] ?? '';

abort_unless(ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300, 401);

$expected = hash_hmac('sha256', "v2:{$timestamp}:".$request->getContent(), $secret);

abort_unless(hash_equals($expected, $elements['v2'] ?? ''), 401);

The original X-Spaw-Signature — the same HMAC over the body alone, with no timestamp — is still sent beside it until 1 March 2027, so a receiver written against it keeps working while you move over.

POST /api/v1/email/feedback

Bounce feedback

Tell us what actually happened to an address after you sent to it. Each outcome is stored against the verdict you had been given for that address in the previous 90 days, which turns verdicts into measured accuracy, and it keeps your suppression list current: a bounce or complaint adds the address, and a delivery removes an entry a verdict or a bounce added, never a complaint or an import. Free, up to 1,000 items per request; answers 202 with the counts recorded and skipped.

$ curl https://spaw.co/api/v1/email/feedback \
    -H "Authorization: Bearer sk_live_…" \
    -H "Content-Type: application/json" \
    -d '{"items": [{"email": "[email protected]", "outcome": "bounced", "reason": "550 5.1.1 no such user"}]}'

Request

Webhooks from your email provider

Generate a feedback key on the API keys page and point your provider's bounce, delivery, and complaint webhooks at the matching URL below. The key is the only credential a webhook can carry, so rotating it invalidates the URLs at once. Payloads are read for their documented fields and nothing else; events that say nothing definitive about the address are ignored.

Measured accuracy

GET /api/v1/email/feedback/summary crosses the last 90 days of outcomes with the verdicts on file: by_verdict counts delivered, bounced, and complained per verdict, and measured.deliverable_delivery_rate and measured.undeliverable_bounce_rate are the two numbers that say how right we were for you. The same figures appear on the History tab of the dashboard. Outcomes are kept for 180 days. Across accounts, only per-domain delivered-versus-bounced counts are read, and only once a domain has at least five, to inform the mailbox confidence on catch-all domains.