API reference / Email verification

Get a job's results

Written and maintained by The ProspectAPIs team

GET/v1/email/verify/jobs/:id/results

GET /v1/email/verify/jobs/:id/results is the ProspectAPIs operation getEmailVerifyJobResults, in the Email verification group of the REST API. Results in input order, up to 1,000 a page from cursor; next_cursor is null on the last page. An address not yet checked has status pending. Add format=csv for a CSV page (the next cursor is in the X-Next-Cursor header). Free. Cost: free. Send your API key as a Bearer token in the Authorization header.

How this fits with the rest of the email verification API, with worked examples, is in the email verification guide.

Parameters

Parameters of GET /v1/email/verify/jobs/:id/results
Name	In	Type	Description
id required	path	string (uuid)
cursor	query	integer
limit	query	integer	1 to 1000.
format	query	string: json, csv

An unknown query parameter is refused with a 400 rather than ignored, so a typo never widens a search you pay for.

Responses

Response codes of GET /v1/email/verify/jobs/:id/results
Status	Meaning
200	A page of results.
401	The API key is missing or invalid.
404	No such job on this account.

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens.

200 response fields

A page of results.

Fields of the 200 response
Field	Type	Description
job	EmailVerifyJob
job.id required	string (uuid)
job.status required	string: queued, running, completed, cancelled
job.total required	integer
job.done required	integer
job.charged_count required	integer
job.amount_usd required	number
job.callback_url	string or null
job.callback_status	string or null: delivered, failed,
job.created_at required	string (date-time)
job.completed_at	string (date-time) or null
job.secret	string	Only in the 202 create response: the HMAC key for the completion callback's Prospect-Signature header.
data	array of EmailVerifyResult
data[].email required	string
data[].status required	string: valid, invalid, catch-all, unknown
data[].reason required	string	Why the address got its status, e.g. not_checked_insufficient_credits.
data[].reason_text required	string	The reason in plain words.
data[].score required	integer	How likely mail to this address is to arrive, from every signal the check returned. 0 to 100.
data[].recommendation required	string: send, send_with_caution, retry_later, do_not_send	The action to take with this address.
data[].charged required	boolean	Whether this result was billed.
data[].flags required	array of string
data[].smtp_code required	integer or null	The mail server's reply code, when the check reached one.
data[].catch_all_tier required	string or null	For a catch-all domain, how likely the address is to be real.
data[].did_you_mean	string or null	A likely typo of a common mail domain, for example gmail.com for gmial.com.
data[].mail_provider	string or null: google, microsoft, yahoo, proofpoint, mimecast, other,	Who runs the domain's mail.
data[].checked_at	string (date-time)	When the mail server was asked; for a cached result, when that check ran.
data[].cache_age_days	integer	Present when the result came from a check of the same address in the last 30 days (valid) or 90 days (invalid): its age in days. Billed like a fresh check.
next_cursor	integer or null

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl

curl https://api.prospectapis.com/v1/email/verify/jobs/3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13/results \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY"

JavaScript (fetch)

const res = await fetch("https://api.prospectapis.com/v1/email/verify/jobs/3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13/results", {
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

Python (requests)

import os, requests

res = requests.get(
    "https://api.prospectapis.com/v1/email/verify/jobs/3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13/results",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

This call is free: it never spends credits, so you can call it as often as the rate limit allows. Metered calls on the same key report your balance after each response in X-Credits-Remaining, and GET /v1/account shows it at any time.

The email verification guide covers this area end to end. Previous operation: Get a verification job. Next operation: Stop a verification job. Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values.

Was this page helpful?