API reference / Verify email

Verify email

Validate a single address in real time, or a small synchronous batch of up to 30. Every check runs the full pipeline (syntax, DNS/MX, disposable, role, free provider, and a live SMTP mailbox probe) and returns a clear verdict with a graded risk score.

POST/v1/verify/batchVerify up to 30 email addresses in a single request (interactive "paste a batch" path)POST/v1/verify/singleVerify a single email address GET/v1/verify/singleVerify a single email address

POST/v1/verify/batch

Verify up to 30 email addresses in a single request (interactive "paste a batch" path)

Addresses are de-duplicated (by canonical form) before probing, so the same address pasted twice costs one credit. Each result follows the same credit rules as single verify. Send an Idempotency-Key header to make a retry replay the prior response with no re-charge.

Request body application/json

Field	Type	Required	Description
emails	string[]	optional

Response 200 · inside data

Field	Type	Description	Example
results	VerifyResponse[]
summary	BatchSummary	Roll-up counts for a batch, so the UI can show a summary strip without recomputing.

Returns 400, 401, 402 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X POST "https://api.primeverifier.com/v1/verify/batch" \
  -H "X-API-KEY: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "[email protected]"
    ]
  }'

const res = await fetch("https://api.primeverifier.com/v1/verify/batch", {
  method: "POST",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "emails": [
      "[email protected]"
    ]
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.primeverifier.com/v1/verify/batch",
    headers={"X-API-KEY": "pk_live_your_api_key"},
    json={"emails": ["[email protected]"]},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.primeverifier.com/v1/verify/batch");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
req.Content = new StringContent("{\"emails\":[\"[email protected]\"]}",
    Encoding.UTF8, "application/json");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/verify/batch"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"emails\":[\"[email protected]\"]}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/verify/batch");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["emails" => ["[email protected]"]]),
]);
$response = curl_exec($ch);
echo $response;

body := strings.NewReader(`{"emails":["[email protected]"]}`)
req, _ := http.NewRequest("POST", "https://api.primeverifier.com/v1/verify/batch", body)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/verify/batch")
req = Net::HTTP::Post.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
req["Content-Type"] = "application/json"
req.body = { emails: ["[email protected]"] }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {
    "results": [
      {
        "email": "[email protected]",
        "result": "ok",
        "resultCode": 1,
        "subResult": "ok",
        "quality": "good",
        "free": false,
        "role": false,
        "disposable": false,
        "catchAll": false,
        "didYouMean": "[email protected]",
        "provider": "google",
        "antiSpam": false,
        "riskScore": 5,
        "creditsCharged": 1,
        "creditsRemaining": 49999,
        "executionMs": 420
      }
    ],
    "summary": {
      "total": 0,
      "valid": 0,
      "invalid": 0,
      "catchAll": 0,
      "unknown": 0,
      "disposable": 0,
      "error": 0,
      "creditsCharged": 0,
      "creditsRemaining": 0
    }
  },
  "error": null
}

Try itPOST /v1/verify/batch

API key *

Request body (JSON)

Runs a real request against api.primeverifier.com. A decisive verification may use 1 credit.

POST/v1/verify/single

Verify a single email address

Runs the full 10-step verification pipeline: syntax → normalize → did-you-mean → MX → disposable → free provider → role → SMTP → risk scorer → quality mapping.

Credit cost: 1 credit for ok, invalid, disposable, catch_all. unknown and error results are free.

Request body application/json

Field	Type	Required	Description
email	string · null	optional

Response 200 · inside data

Field	Type	Description	Example
email	string · null	The email address that was verified, echoed back from your request.	"[email protected]"
result	string · null	Headline verdict: one of `ok`, `invalid`, `catch_all`, `unknown`, `disposable`, or `error`.	"ok"
resultCode	integer · int32	Numeric form of `result`: 1 ok, 2 catch_all, 3 unknown, 4 error, 5 disposable, 6 invalid.	1
subResult	string · null	Precise reason from the mail server, from the public sub-result set (`ok`, `greylisted`, `ip_blocked`, `mailbox_full`, `no_mailbox`, `invalid_syntax`, `dns_error`, `timeout`, ...). Null when there is none.	"ok"
quality	string · null	One-word send recommendation: `good`, `risky`, or `bad`. Empty for an `error` result.	"good"
free	boolean	True when the address is on a free consumer provider such as gmail.com or yahoo.com.	false
role	boolean	True when this is a role address (info@, support@, sales@) rather than a person.	false
disposable	boolean	True when the domain is a throwaway or temporary-inbox provider.	false
catchAll	boolean	True when the domain accepts every recipient, so the exact mailbox cannot be isolated.	false
didYouMean	string · null	A suggested correction when the address looks mistyped (gmial.com becomes gmail.com). Null when nothing looks wrong.	"[email protected]"
provider	string · null	The mailbox provider when detected (`google`, `microsoft`, `yahoo`, ...). Empty if unknown.	"google"
antiSpam	boolean	True when a security or anti-spam gateway (Proofpoint, Mimecast, Barracuda) sits in front of the domain.	false
riskScore	integer · int32	Graded risk from 0 to 100, banded to match `quality`: 0 to 29 good (safe to send), 30 to 69 risky, 70 to 100 bad. Lower is safer.	5
creditsCharged	integer · int32	Credits charged for this call: 1 on a decisive result (ok, catch_all, disposable, invalid), 0 on unknown or error.	1
creditsRemaining	integer · int64	Your remaining credit balance after this call.	49999
executionMs	integer · int32	How long the verification took, in milliseconds.	420

Returns 400, 401, 402 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X POST "https://api.primeverifier.com/v1/verify/single" \
  -H "X-API-KEY: pk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

const res = await fetch("https://api.primeverifier.com/v1/verify/single", {
  method: "POST",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "[email protected]"
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://api.primeverifier.com/v1/verify/single",
    headers={"X-API-KEY": "pk_live_your_api_key"},
    json={"email": "[email protected]"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.primeverifier.com/v1/verify/single");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
req.Content = new StringContent("{\"email\":\"[email protected]\"}",
    Encoding.UTF8, "application/json");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/verify/single"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"email\":\"[email protected]\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/verify/single");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["email" => "[email protected]"]),
]);
$response = curl_exec($ch);
echo $response;

body := strings.NewReader(`{"email":"[email protected]"}`)
req, _ := http.NewRequest("POST", "https://api.primeverifier.com/v1/verify/single", body)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/verify/single")
req = Net::HTTP::Post.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
req["Content-Type"] = "application/json"
req.body = { email: "[email protected]" }.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {
    "email": "[email protected]",
    "result": "ok",
    "resultCode": 1,
    "subResult": "ok",
    "quality": "good",
    "free": false,
    "role": false,
    "disposable": false,
    "catchAll": false,
    "didYouMean": "[email protected]",
    "provider": "google",
    "antiSpam": false,
    "riskScore": 5,
    "creditsCharged": 1,
    "creditsRemaining": 49999,
    "executionMs": 420
  },
  "error": null
}

Try itPOST /v1/verify/single

API key *

Request body (JSON)

Runs a real request against api.primeverifier.com. A decisive verification may use 1 credit.

GET/v1/verify/single

Verify a single email address

Identical to the POST variant. Example: GET /v1/verify/[email protected]

Parameters

Name	In	Type	Required	Description
email	query	string	optional	The email address to verify.

Response 200 · inside data

Field	Type	Description	Example
email	string · null	The email address that was verified, echoed back from your request.	"[email protected]"
result	string · null	Headline verdict: one of `ok`, `invalid`, `catch_all`, `unknown`, `disposable`, or `error`.	"ok"
resultCode	integer · int32	Numeric form of `result`: 1 ok, 2 catch_all, 3 unknown, 4 error, 5 disposable, 6 invalid.	1
subResult	string · null	Precise reason from the mail server, from the public sub-result set (`ok`, `greylisted`, `ip_blocked`, `mailbox_full`, `no_mailbox`, `invalid_syntax`, `dns_error`, `timeout`, ...). Null when there is none.	"ok"
quality	string · null	One-word send recommendation: `good`, `risky`, or `bad`. Empty for an `error` result.	"good"
free	boolean	True when the address is on a free consumer provider such as gmail.com or yahoo.com.	false
role	boolean	True when this is a role address (info@, support@, sales@) rather than a person.	false
disposable	boolean	True when the domain is a throwaway or temporary-inbox provider.	false
catchAll	boolean	True when the domain accepts every recipient, so the exact mailbox cannot be isolated.	false
didYouMean	string · null	A suggested correction when the address looks mistyped (gmial.com becomes gmail.com). Null when nothing looks wrong.	"[email protected]"
provider	string · null	The mailbox provider when detected (`google`, `microsoft`, `yahoo`, ...). Empty if unknown.	"google"
antiSpam	boolean	True when a security or anti-spam gateway (Proofpoint, Mimecast, Barracuda) sits in front of the domain.	false
riskScore	integer · int32	Graded risk from 0 to 100, banded to match `quality`: 0 to 29 good (safe to send), 30 to 69 risky, 70 to 100 bad. Lower is safer.	5
creditsCharged	integer · int32	Credits charged for this call: 1 on a decisive result (ok, catch_all, disposable, invalid), 0 on unknown or error.	1
creditsRemaining	integer · int64	Your remaining credit balance after this call.	49999
executionMs	integer · int32	How long the verification took, in milliseconds.	420

Returns 400, 401, 402 with the error envelope { status, error: { code, message } }. Branch on the numeric error.code, never the message.

Request

curl -X GET "https://api.primeverifier.com/v1/verify/single?email=jane.doe%40acme.com" \
  -H "X-API-KEY: pk_live_your_api_key"

const res = await fetch("https://api.primeverifier.com/v1/verify/single?email=jane.doe%40acme.com", {
  method: "GET",
  headers: {
    "X-API-KEY": "pk_live_your_api_key",
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.primeverifier.com/v1/verify/single?email=jane.doe%40acme.com",
    headers={"X-API-KEY": "pk_live_your_api_key"},
)
print(res.json())

using var client = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Get, "https://api.primeverifier.com/v1/verify/single?email=jane.doe%40acme.com");
req.Headers.Add("X-API-KEY", "pk_live_your_api_key");
var res = await client.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.primeverifier.com/v1/verify/single?email=jane.doe%40acme.com"))
    .header("X-API-KEY", "pk_live_your_api_key")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

$ch = curl_init("https://api.primeverifier.com/v1/verify/single?email=jane.doe%40acme.com");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => ["X-API-KEY: pk_live_your_api_key"],
]);
$response = curl_exec($ch);
echo $response;

req, _ := http.NewRequest("GET", "https://api.primeverifier.com/v1/verify/single?email=jane.doe%40acme.com", nil)
req.Header.Set("X-API-KEY", "pk_live_your_api_key")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))

require "net/http"
require "json"

uri = URI("https://api.primeverifier.com/v1/verify/single?email=jane.doe%40acme.com")
req = Net::HTTP::Get.new(uri)
req["X-API-KEY"] = "pk_live_your_api_key"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

Response200 OK

{
  "status": "success",
  "data": {
    "email": "[email protected]",
    "result": "ok",
    "resultCode": 1,
    "subResult": "ok",
    "quality": "good",
    "free": false,
    "role": false,
    "disposable": false,
    "catchAll": false,
    "didYouMean": "[email protected]",
    "provider": "google",
    "antiSpam": false,
    "riskScore": 5,
    "creditsCharged": 1,
    "creditsRemaining": 49999,
    "executionMs": 420
  },
  "error": null
}

Try itGET /v1/verify/single

API key *

email (query)