API reference / Email verification

Start a verification job

Written and maintained by The ProspectAPIs team

POST/v1/email/verify/jobs

POST /v1/email/verify/jobs is the ProspectAPIs operation createEmailVerifyJob, in the Email verification group of the REST API. Check up to 50,000 addresses in the background. Answers 202 with the job; the signing secret for the completion callback is in this response only. A slow or greylisting server is retried about 5, 15 and 30 minutes later, free. Each valid or invalid result is charged at the verification price as it is checked; catch-all and unknown are free; when the balance runs out, the rest come back unknown with reason not_checked_insufficient_credits. At most 5 jobs run at once per account (429). Results are kept 7 days after completion. Cost: free to create; $0.004 per definite result as it is checked. 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

This operation takes no path or query parameters.

Request body

JSON.

{
  "emails": [
    "emails"
  ]
}

Responses

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. A per-key 429 carries Retry-After; see rate limits.

202 response fields

The job, with its secret. The body is a EmailVerifyJob.

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 -X POST https://api.prospectapis.com/v1/email/verify/jobs \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": [ "emails" ] }'

const res = await fetch("https://api.prospectapis.com/v1/email/verify/jobs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "emails": [
      "emails"
    ]
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

import os, requests

res = requests.post(
    "https://api.prospectapis.com/v1/email/verify/jobs",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    json={
        "emails": ["emails"],
    },
    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.

Related

The email verification guide covers this area end to end. Previous operation: Clean a list. Next operation: Get 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 (this call acts for real, so use real inputs).