Email Verification API.

Verify one address or a list of up to 100,000 over REST, and read back a status, a reason and an action for each, paying only for definitive answers.

curl -X POST https://api.unspam.email/ext/v2/email-verification/instant-checks \
  -H "Authorization: Bearer $UNSPAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@acme.com" }'

# poll the id until the check has finished
curl https://api.unspam.email/ext/v2/email-verification/instant-checks/8d3f1a2b \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# response (200)
{
  "status": "completed",
  "charged": true,
  "result": {
    "status": "deliverable",
    "reason": "accepted",
    "action": "keep",
    "flags": ["free_provider"],
    "did_you_mean": null
  }
}
curl -X POST https://api.unspam.email/ext/v2/email-verification/list-checks \
  -H "Authorization: Bearer $UNSPAM_TOKEN" \
  -F "file=@leads.csv"

# the list is analysed, then verified: read it for progress
curl https://api.unspam.email/ext/v2/email-verification/list-checks/5c2e9f10 \
  -H "Authorization: Bearer $UNSPAM_TOKEN"

# response (200)
{
  "status": "verifying",
  "rows_total": 12480,
  "duplicates": 311,
  "progress": { "processed": 4200, "total": 12046 }
}

# once it has finished, page through every address in the order sent
curl https://api.unspam.email/ext/v2/email-verification/list-checks/5c2e9f10/results \
  -H "Authorization: Bearer $UNSPAM_TOKEN"
Endpoints
5
Addresses per list
100,000
Authentication
Bearer token
Rate limit
100 a minute

What the API checks on every address.

Syntax, domain and mail server

Each address is parsed, its domain resolved and its MX records read, so typos and domains that no longer take mail are caught before a mailbox is asked anything.

Mailbox, catch-all and full inbox

The mail server is asked whether the mailbox exists, without sending a message. Catch-all domains, full inboxes and disabled mailboxes each come back as their own reason.

Disposable, role and free provider

Flags mark disposable domains, role addresses such as info@ and sales@, and free providers, so your code decides how to treat each one.

Typo suggestions

When an address looks like a typo, did_you_mean carries the likely intended one, such as jane@gmail.com for jane@gmial.com.

One address, a whole list, or an AI assistant.

Two ways in over REST and one over MCP, all on the same token and the same verification engine.

Verify a single address

Send an address and get an id back at once. Read it until its status is completed or failed, then branch on the result: deliverable, risky, undeliverable or unknown, with a reason, an action and the domain, mail server and mailbox detail behind it.

The check is asynchronous, so it fits where a short wait is fine: a contact before it enters your CRM, a lead before a sequence, an address before a one-off send. It is not a synchronous check that holds a signup form until it answers.

  • jane@acme.com accepted
  • sales@northwind.io catch_all
  • lead@oldco.invalid invalid_domain
  • mark@yahoo.com provider_unverifiable

Verify a whole list

Send up to 100,000 addresses as JSON, or upload a CSV or TXT file of up to 20 MB and let the API find the address column and the header row. Duplicates and malformed rows are counted and skipped, never charged, and a list your credits cannot cover is refused before a single check runs.

Read progress from the list itself until it ends as completed, failed, cancelled or expired, then page through every result in the order you sent it. Lists and their results are deleted 30 days after upload.

  • Deliverable 10,512
  • Risky 842
  • Undeliverable 415
  • Unknown, not charged 277

Let an AI assistant run it

The same checks are tools on the Unspam MCP server, so Claude, Cursor or any remote MCP client can verify an address or a list from a conversation and read back each result with its reason.

Five tools: verify_email, get_email_verification, create_email_list, get_email_list and get_email_list_results.

  • Verify one address verify_email
  • Verify a list create_email_list
  • Read the results get_email_list_results

What every result tells you.

Four fields carry the answer, so your code branches on one value and still has the detail when it needs it.

  1. 01

    status

    Deliverable, risky, undeliverable or unknown: the one field to branch on.

  2. 02

    reason

    Why it got that status: accepted, catch_all, full_inbox, disposable, invalid_syntax, invalid_domain, rejected, disabled, timeout, smtp_unavailable, provider_unverifiable or unknown.

  3. 03

    action

    Keep, review, remove or retry, so you do not have to map every reason to a decision yourself.

  4. 04

    charged

    Whether the check used a credit. Unknown answers, duplicates and malformed addresses never do.

The endpoints behind it.

5 endpoints, on the same token as the rest of the API. The OpenAPI document has every parameter and response code.

OpenAPI document
Email Verification 5 calls
  • POST /email-verification/instant-checks
  • GET /email-verification/instant-checks/{id}
  • POST /email-verification/list-checks
  • GET /email-verification/list-checks/{id}
  • GET /email-verification/list-checks/{id}/results

Questions about the email verification API.

Pricing, speed, unknown results, lists and AI assistants.

How much does the email verification API cost?
API access comes with the Custom plan, from a $5 monthly minimum. Verification is priced band by band, from $6.40 per 1,000 addresses down to $1.20 per 1,000 above 100,000, and only definitive answers use a credit. Unknown answers, duplicates and malformed addresses are free, and you can top up credits without changing plan.
Is there a free email verification API?
The first 10 single checks each day are free, through the API as well as in the app, and an unknown answer is never charged. To try it without an account, the email verifier checks up to 10 addresses a day with no sign-up.
Is the email verification API real-time?
It is asynchronous. A check starts at once and answers with an id, and you read the result when its status is completed, or stop if it is failed. That suits imports, CRM syncs, lead routing and list cleaning. A synchronous check that holds a signup form until it answers is not offered today.
What is the difference between email validation and email verification?
Validation usually means checking that an address is well formed and that its domain can receive mail. Verification goes on to ask the mail server whether the mailbox exists. The API does both in one call: syntax, domain and MX first, then the mailbox, catch-all and full inbox checks.
Why do some addresses come back unknown?
Yahoo and AOL accept every address during a mailbox check, so no verifier can confirm those mailboxes: they come back unknown with the reason provider_unverifiable. A mail server that times out or does not answer also ends unknown, with the reason timeout or smtp_unavailable and the action retry. Unknown answers are never charged.
How do I verify a whole list through the API?
Send the addresses as a JSON array, or upload a CSV or TXT file of up to 100,000 rows and 20 MB. The API finds the address column and the header row, counts duplicates and malformed rows without charging them, and starts verifying once the list is analysed. Read the list for progress and a summary, then page through the results.
Can an AI assistant verify email addresses with Unspam?
Yes. The Unspam MCP server exposes verification as five tools, so Claude, Cursor or any remote MCP client can verify one address or a whole list and read back each result with its reason and action.
Is the list data kept?
Lists and their results are deleted 30 days after upload, and the results endpoint answers 410 Gone after that. Addresses are checked against the mail server without sending a message to anyone.

Verify your first list through the API.

API access comes with the Custom plan, from a $5 monthly minimum. Pay only for definitive answers, from $6.40 per 1,000 addresses.