Email verification endpoint — Verify Email Address API Documentation

Verify an email address with one POST request. Authentication, parameters, responses, credit usage, and errors are documented on this page.

POST/api/v1/email-verification

Authentication

Every request uses the following authentication method.

Authorization: Bearer YOUR_API_KEY

Protect API keys

Store and use API keys only on your server. Delete and replace a key immediately if it may be compromised.

Request body

FieldTypeDescription

emailRequired

string

The email address to verify. Maximum length: 254 characters.

Request example

curl --request POST \  --url https://verifyemailaddress.net/api/v1/email-verification \  --header 'Authorization: Bearer YOUR_API_KEY' \  --header 'Content-Type: application/json' \  --data '{"email":"name@example.com"}'

Response examples

A completed verification returns HTTP 200. Common result examples are shown below; the actual response contains only the signals available for that verification.

Deliverable

{  "email": "name@example.com",  "status": "safe",  "overall_score": 98,  "username": "name",  "domain": "example.com",  "is_safe_to_send": true,  "is_valid_syntax": true,  "is_disposable": false,  "is_role_account": false,  "can_connect_smtp": true,  "has_inbox_full": false,  "is_catch_all": false,  "is_deliverable": true,  "is_disabled": false,  "is_spamtrap": false,  "is_free_email": false,  "mx_accepts_mail": true,  "mx_records": ["mx.example.com"],  "verification_mode": "power"}

Undeliverable

{  "email": "missing@example.com",  "status": "invalid",  "overall_score": 0,  "username": "missing",  "domain": "example.com",  "is_safe_to_send": false,  "is_valid_syntax": true,  "is_disposable": false,  "is_role_account": false,  "can_connect_smtp": true,  "has_inbox_full": false,  "is_catch_all": false,  "is_deliverable": false,  "is_disabled": false,  "is_spamtrap": false,  "is_free_email": false,  "mx_accepts_mail": true,  "mx_records": ["mx.example.com"],  "verification_mode": "power"}

Catch-all domain

{  "email": "name@example.com",  "status": "catch_all",  "overall_score": 75,  "username": "name",  "domain": "example.com",  "is_safe_to_send": false,  "is_valid_syntax": true,  "is_disposable": false,  "is_role_account": false,  "can_connect_smtp": true,  "has_inbox_full": false,  "is_catch_all": true,  "is_deliverable": true,  "is_disabled": false,  "is_spamtrap": false,  "is_free_email": false,  "mx_accepts_mail": true,  "mx_records": ["mx.example.com"],  "verification_mode": "power"}

Unknown

{  "email": "name@example.com",  "status": "unknown",  "username": "name",  "domain": "example.com",  "is_valid_syntax": true,  "is_disposable": false,  "is_role_account": false,  "is_free_email": false,  "mx_accepts_mail": true,  "mx_records": ["mx.example.com"],  "verification_mode": "power"}

Response headers

FieldTypeDescription

X-Request-Id

string

Unique request ID. Include it when contacting support.

X-Credits-Used

0 | 1

The number of credits charged for this request.

Response fields

Receiving systems expose different information, so these fields are returned according to the signals available for the verification.

FieldTypeDescription

email

string

The email address that was verified.

status

string

Verification status: safe, invalid, disabled, disposable, inbox_full, catch_all, role_account, spamtrap, or unknown.

overall_score

number

Verification score available for the result.

username

string

The part of the email address before the @ sign.

domain

string

The domain used by the email address.

is_safe_to_send

boolean

Whether the available delivery signals support sending.

is_valid_syntax

boolean

Whether the address follows email syntax rules.

mx_accepts_mail

boolean

Whether the domain is configured to receive email.

can_connect_smtp

boolean

Whether an SMTP connection was established.

has_inbox_full

boolean

Whether the mailbox is full.

is_deliverable

boolean

Whether the mailbox was reported as deliverable.

is_disposable

boolean

Whether the address belongs to a disposable email service.

is_role_account

boolean

Whether the address represents a role such as support@.

is_catch_all

boolean

Whether the server accepts mail for addresses that may not exist.

is_disabled

boolean

Whether the mailbox is disabled.

is_spamtrap

boolean

Whether the address is identified as a spam trap.

is_free_email

boolean

Whether the address uses a common free email provider.

mx_records

string[]

Mail-server records returned for the domain.

verification_mode

"power"

Verification mode used for the request.

Credit usage

Each request reserves one credit. It is charged only when verification produces a conclusive result and is returned automatically when no result is obtained.

FieldTypeDescription

Completed

1 credit

Verification completed and returned a usable, conclusive result.

Inconclusive

No charge

The receiving server did not expose enough information for a conclusive result.

Failed request

No charge

The request was rejected, unavailable, failed, or timed out.

Error responses

Error responses use the same JSON shape. Every possible status is shown directly below.

{  "status": "error",  "reason": "invalid_api_key"}

HTTP	reason	Description
`400`	`invalid_email`	The request does not contain a valid email address.
`401`	`invalid_api_key`	The API key is missing, invalid, or deleted.
`403`	`subscription_required`	The account does not have an active paid plan.
`405`	`method_not_allowed`	The endpoint must be called with POST.
`429`	`insufficient_credits`	The account does not have enough available credits.
`500`	`verification_failed`	Verification failed unexpectedly.
`502`	`verification_unavailable`	A verification result could not be obtained.
`503`	`service_unavailable`	Email verification is temporarily unavailable.
`504`	`verification_timeout`	Verification did not finish before the timeout.