Verifalia exposes a RESTful email validation API which is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors.

Not a software developer?

Verifalia is a web-based email validation service which allows to upload and validate lists of email addresses with ease: you don't need to be a software developer to use Verifalia!

Just upload your list of email addresses and we will validate them for you, giving you back a detailed report.

This content refers to a previous version of our developers API and we are no longer updating it regularly.

Check out the documentation for the latest API version

Using the Verifalia API

Verifalia comes with SDKs for the most common development platforms and programming languages; these SDKs are wrappers on top of our RESTful API which allow to easily integrate our email verification service into you own apps or websites, often with just a single line of code. Using our SDKs is recommended to get the best from our service: each Verifalia SDK is free and open-source, with its source code available on Github.

Authentication

For security reasons, authentication to the Verifalia API is performed by way of Verifalia sub-accounts credentials only, where a sub-account is an entity which helps you securely control access to Verifalia resources. You can easily create a sub-account from your Verifalia dashboard (API and sub-accounts pane) and define its login and password - called, respectively sub-account SID and auth-token -, as well as its permissions, there.

Data interchange format

The data interchange format for the Verifalia API is JSON encoded as UTF-8, where the body of every POST and PUT requests made against the API should have a MIME content type header set to application/json. Wherever the API returns a response with a body, its format is still a JSON object encoded as UTF-8 and it comes with the aforementioned MIME content type header.

API endpoints (base URLs)

v1.2+ Verifalia provides two distinct endpoints for API consumption, with identical features and behavior, which are used to increase the service availability and speed. These endpoints, which are the base for all the URLs referenced in this documentation, are:

https://api-1.verifalia.com/v1.4
https://api-2.verifalia.com/v1.4

Most Verifalia official SDKs already implement an automatic retry, fail-safe logic, so you don't have to worry about picking one API endpoint or the other. If you are developing a custom API SDK, however, it is recommended that for each API request, the client picks a random endpoint and, in the event of failure, uses the next one and retries the original request.

Single base URL

While we recommend applying an automatic retry logic to the distinct endpoints mentioned above - which allows to be backed by our premium uptime SLA -, we also support a single API DNS record api.verifalia.com which points to the aforementioned API hosts, in a round-robin fashion. Thus, simpler client implementations which can't afford implementing a full auto-retry logic (cURL, for example) may point to this single base URL instead:

https://api.verifalia.com/v1.4

Endpoints security

The Verifalia REST API is served over HTTPS only: to ensure data privacy, unencrypted HTTP is not supported. Also, our HTTPS endpoints require your web client to support Server Name Indication (SNI), a standard widespread extension to the TLS protocol which may be missing in some obsolete systems (most notably, in Microsoft Windows XP and lower version operating systems as well as in wget prior to version 1.14).

For additional safety, our endpoints support these TLS protocol versions:

TLS 1.0 Deprecated
TLS 1.1
TLS 1.2

API limits

To help prevent strain on Verifalia’s servers, our API imposes a rate limit of 5 concurrent API invocations per IP address, meaning a single IP address can't have more than 5 overlapping HTTP requests to our API endpoints at the same time. This does not limit the number of concurrent running email validation jobs a single IP address or account may have however, which is unlimited at the time of this writing. If a request exceeds the limit, we return an HTTP 429 status code.

HTTP status codes

The Verifalia API uses conventional HTTP status codes to indicate success or failure of a request. Here are the possible HTTP status codes which the API may return:

HTTP status code	Meaning
`200`	Success. The API request completed without any error.
`202`	Accepted. The API request has been queued and will be completed as soon as possible by the system.
`400`	Bad request. Perhaps you are not sending a required parameter or not passing the information using JSON.
`401`	Unauthorized request. No valid sub-account SID or auth token (that is, the credentials of the sub-account) provided; please see how to authenticate to the Verifalia API for additional details.
`402`	Payment required. Either the credit of your account is too low to process the validation request or the request would exceed the maximum number of monthly processable items.
`404`	Not found. The requested resource does not exist on the server.
`406`	Not acceptable. The requested resource is not available with respect to its current state.
`410`	Gone. The requested resource has been deleted and is no longer available on the server.
`429`	Too many requests. Returned when a request cannot be served due to the application's rate limit having been exhausted for the client.
`5xx`	Server error. Verifalia failed to fulfill an apparently valid request.

Email validations

To start validating a list of one or more email addresses, you create a new email validation job. Email validation jobs are identified by a unique random ID (for example: 54375b5b-a399-4bc4-abd8-b8c02e109e53) and live in the following sub-resource:

/email-validations

Submitting a new validation

To create a new email validation job you can issue an HTTP POST request against the /email-validations sub-resource, along with the email addresses you wish to include in the job; upon receipt of the request, Verifalia queues the validations and process them asynchronously. In fact, because of the unpredictable processing time email validations may require, it would be impractical for the client to wait indefinitely.

As part of the response to the new email validation request, Verifalia sends back an object representing the result snapshot of the current email validation request, along with an auto-generated unique ID for the job and an URL (via the Location HTTP header) the client must poll in order to receive updated snapshots in the future.

For higher subscription plans, Verifalia can complete a validation request within a very short time-frame: in this case, the result snapshot returned upon the creation of the job already contains the individual validation items results and there is no need for a subsequent additional poll.

The request body must be a JSON object with this structure:

entries[]
an array of addresses to process
- inputData
  the email address you wish to validate.
- custom
  v1.2+ an optional string with custom data to be returned upon completion, with a maximum length of 50 characters.
quality
v1.2+ an optional string with the name of the desired results quality; can be any of the following: standard, high, extreme. If not specified, Verifalia will use the default results quality for your account.
priority
v1.4+ an optional numeric value which sets the priority of the validation activity, relative to the parent subscription. In the event of a subscription with many concurrent jobs, this value allows to increase the processing slot time percentage of a validation job with respect to the others. The allowed range of integer values spans from 0 (lowest priority) to 255 (highest priority), where the midway value 127 means normal priority; if not specified, Verifalia processes the validation job without a specific priority.
deduplication
v1.4+ an optional string with the name of the algorithm our engine will use to scrub the list of email addresses and remove its duplicates. The following values are currently supported:
- off does not mark duplicated items
- safe mark duplicated items with a "safe" algorithm which guarantees no false duplicates are returned
If not specified, Verifalia will use the default settings for the subscription.

Request structure example (JSON)

{
    entries: [
        { inputData: 'john.smith@example.com' },
        { inputData: 'batman@example.net', custom: 'c_123' },
        { inputData: 'foo@inv@lid.tld' }
    ],
    quality: 'high',
    priority: 100,
    deduplication: 'safe'
}

Example, using CURL

curl -i -H "Content-Type: application/json"
    -d "{ entries: [ { inputData: 'batman@gmail.com' } ] }"
    -u MyAccountSid:MyAuthToken
    https://api.verifalia.com/v1.4/email-validations

Getting validation results

To retrieve the status of a particular email validation job, the client asks Verifalia for an updated snapshot by issuing an HTTP GET request against the /email-validations/{uniqueId} sub-resource, where uniqueId is the random unique ID returned by Verifalia upon creating the validation job.

Verifalia replies back with an object representing the result snapshot of the requested job. Should the validation be still in progress, the system would reply with an HTTP 202 (Accepted) status code and the client should reissue the request to retrieve an updated result snapshot.

Example, using CURL

curl https://api.verifalia.com/v1.4/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53
     -u MyAccountSid:MyAuthToken

Result snapshot

In response to a new email validation request and whenever you request it directly, Verifalia sends replies with an object representing the snapshot of the current email validation request.

Email validation snapshots have the following data structure:

{

uniqueID
a unique, random ID assigned by Verifalia to the validation batch
engineVersion
a string representing the internal Verifalia engine version
submittedOn
date and time (UTC) the batch has been submitted
completedOn
date and time (UTC) the batch has been completed, if available
priority
v1.4+ the batch priority, relative to the other batches running within the same Verifalia subscription. It comes as a numeric value, between 0 and 255, where the default ( 127, normal priority) is omitted for brevity from the snapshot.
progress
an object whose members represent the validation progress:

{
- noOfTotalEntries
  the number of total entries being validated
- noOfCompletedEntries
  the number of validated entries
- estimatedRemainingTime
  v1.4+ the total estimated time required to finish validating the job, if available, expressed in the format dd.hh:mm:ss (where dd: days, hh: hours, mm: minutes, ss: seconds), where the initial dd. part is added only for huge lists requiring more than 24 hours to complete.
}
entries
an array with the validation results, if available:

[
{
- inputData
  the original input string passed to Verifalia (for reference purposes).
- status
  the validation status for this entry. Can be one of the supported validation status codes.
- completedOn
  date and time (UTC) the item has been completed.
- emailAddress
  the email address, without comments and folding white spaces (FWS).
- asciiEmailAddressDomainPart
  the ASCII version of the domain part.
- emailAddressLocalPart
  the local part (or mailbox) of the address.
- emailAddressDomainPart
  the domain part of the address.
- hasInternationalDomainName
  if true, the domain name is international.
- hasInternationalMailboxName
  if true, the mailbox name is international.
- isDisposableEmailAddress
  if true, the address is disposable.
- isFreeEmailAddress
  v1.3+ if true, the address is provided by a free email service provider (e.g. Gmail, Yahoo, Outlook / Live / Hotmail, etc.).
- isRoleAccount
  if true, the address is a well-known role account.
- syntaxFailureIndex
  returns the zero-based index of the syntax failure within the original input data, if any.
- duplicateOf
  v1.4+ available only for entries with a status equals to Duplicate, returns the zero-based index of the first occurrence of the email address the entry appears to be duplicated with.
Shorthand status properties for the status property:
- isSuccess
  if true, the status indicates a success.
- isSyntaxFailure
  if true, the status indicates a syntax issue.
- isDnsFailure
  if true, the status indicates a DNS issue.
- isSmtpFailure
  if true, the status indicates a SMTP issue.
- isMailboxFailure
  if true, the status indicates a mailbox issue.
- isCatchAllFailure
  if true, the status indicates a catch-all issue.
- isTimeoutFailure
  if true, the status indicates a timeout issue.
- isNetworkFailure
  if true, the status indicates a network issue.
},
{ ... }
Eventual additional entries with the same JSON structure, one for each email address of the submitted validation job.
]

}

Email validation structure example (JSON)

{
    uniqueID: '1f977ae169024721869cdadbadc3f754',
    engineVersion: '2017-06-29,rev1',
    submittedOn: '2018-01-30T09:07:13',
    entries: [
        {
            inputData: 'john.smith@example.com',
            completedOn: '2018-01-30T09:07:14',
            emailAddress: 'john.smith@example.com',
            asciiEmailAddressDomainPart: 'example.com',
            emailAddressLocalPart: 'john.smith',
            emailAddressDomainPart: 'example.com',
            hasInternationalDomainName: false,
            hasInternationalMailboxName: false,
            isDisposableEmailAddress: false,
            isRoleAccount: false,
            status: 'SmtpConnectionTimeout',
            syntaxFailureIndex: null,
            isCatchAllFailure: false,
            isSuccess: false,
            isTimeoutFailure: true,
            isNetworkFailure: true,
            isSyntaxFailure: false,
            isDnsFailure: false,
            isSmtpFailure: true,
            isMailboxFailure: false
        },
        {
            // More entries...
        }
    ],
    progress: {
        noOfTotalEntries: 97,
        noOfCompletedEntries: 83,
        estimatedRemainingTime: '00:00:12'
    }
}

Validation status codes

When completed, email validation snapshots bring one or more validation entries along with their email validation statuses. Verifalia defines several different statuses, where every value signals a successful validation or a particular issue.

We may add more statuses to the following list, in the future: your client must be tolerant to new, unknown statuses and treat them as undetermined results, for future compatibility.

Generic status codes

Success
Email address verified successfully.

Syntax status codes

UnmatchedQuotedPair
A quoted pair within a quoted word is not closed properly.
UnexpectedQuotedPairSequence
An unexpected quoted pair sequence has been found within a quoted word.
InvalidWordBoundaryStart
A new word boundary start has been detected at an invalid position.
InvalidCharacterInSequence
An invalid character has been detected in the provided sequence.
UnbalancedCommentParenthesis
The number of parenthesis used to open comments is not equal to the one used to close them.
DoubleDotSequence
An invalid sequence of two adjacent dots has been found.
InvalidLocalPartLength
The local part of the e-mail address has an invalid length.
InvalidFoldingWhiteSpaceSequence
An invalid folding white space (FWS) sequence has been found.
AtSignNotFound
The at sign symbol (@@), used to separate the local part from the domain part of the address, has not been found.
InvalidEmptyQuotedWord
An invalid quoted word with no content has been found.
InvalidAddressLength
The email address has an invalid total length.
DomainPartCompliancyFailure
The domain part of the email address is not compliant with the IETF standards.
IspSpecificSyntaxFailure
According to the syntactic rules of the mail exchanger under test, the email address is invalid.

Disposable status codes

DomainIsWellKnownDea
The e-mail address is provided by a known disposable e-mail address (DEA) provider.

DNS status codes

DomainDoesNotExist
The domain of the e-mail address does not exist.
DnsQueryTimeout
A timeout has occured while querying the DNS server(s) for records about the e-mail address domain. Please try again in a few minutes.
DnsConnectionFailure
A failure has occured while querying the DNS server(s) for records about the e-mail address domain. Please try again in a few minutes.
DomainIsMisconfigured
The domain of the email address is misconfigured and can't receive email messages from the Internet.

SMTP status codes

SmtpConnectionTimeout
A timeout has occured while connecting to the mail exchanger which serves the e-mail address domain.
SmtpConnectionFailure
A socket connection error occured while connecting to the mail exchanger which serves the e-mail address domain.
SmtpDialogError
Failed to validate, the external mail exchanger replied in a non-standard way. Retrying the validation may result in a definitive response.
LocalEndPointRejected
Failed to validate, the external mail exchanger rejected the local end point. Retrying the validation may result in a definitive response.

Mailbox status codes

MailboxDoesNotExist
The mailbox for the e-mail address does not exist.
MailboxConnectionFailure
A connection error occurred while validating the mailbox for the e-mail address.
LocalSenderAddressRejected
The external mail exchanger rejected to accept messages from Verifalia.
MailboxValidationTimeout
A timeout occured while verifying the existence of the mailbox.
MailboxTemporarilyUnavailable
The requested mailbox is temporarily unavailable (perhaps it is over quota). Please note that Verifalia validates email addresses in multiple passes and every temporary condition is checked for up to 20 minutes before having this status applied.
ServerDoesNotSupportInternationalMailboxes
The external mail exchanger does not support international mailbox names, while the supplied address pretend to have one.
MailExchangerIsHoneypot v1.2+
The external mail exchanger hides a honeypot / spam trap.

Catch-all status codes

CatchAllValidationTimeout
A timeout occured while verifying fake e-mail address rejection for the mail server.
ServerIsCatchAll
The external mail exchanger accepts fake, non existent, e-mail addresses; therefore the provided e-mail address MAY be inexistent too.
CatchAllConnectionFailure
A connection error occurred while verifying the external mail exchanger rejects inexistent e-mail addresses.

Duplicates removal / scrub status codes

Duplicate v1.4+
The email address appears to be duplicated with another entry which appears previously in the same validation job. The duplicateOf value contains the zero-based index of the first occurrence of the address within the list.

Miscellaneous status codes

UnhandledException
Failed to validate, we had unexpected technical issues while processing this email address. Retrying the validation may result in a definitive response.

Deleting an email validation job

For security purposes, Verifalia automatically deletes email validation jobs and their results after 30 days since their completion. The client can however force the removal of a completed email validation job by issuing an HTTP DELETE request against the /email-validations/{uniqueId} sub-resource, where uniqueId is the random unique ID returned by Verifalia upon creating the validation job.

Verifalia replies back with an HTTP 200 (OK) status code if the removal succeeded or with an HTTP 410 (Gone) if the job has already been deleted; should the validation be still in progress, the system would reply with an HTTP 406 (Not acceptable) status code.

Example, using CURL

curl -X DELETE https://api.verifalia.com/v1.4/email-validations/54375b5b-a399-4bc4-abd8-b8c02e109e53
     -u MyAccountSid:MyAuthToken

Account

v1.3+ Verifalia provides the ability to check an account balance via the API; of course, clients can also log into their Verifalia dashboard to check their account balance interactively. Each Verifalia account shares its balance with its eventual sub-accounts and, of these, only the ones which are granted the View credit permission can retrieve the balance for their parent Verifalia account.

Account balance

The API client can retrieve its account balance by issuing an HTTP GET request against the following sub-resource:

/account-balance

Verifalia replies back with an HTTP 200 (OK) status code if the operation succeeded or with an HTTP 403 (Forbidden) if the sub-account has not been granted the required View credit permission.

In the first case, Verifalia replies back with a JSON graph representing the balance for the account, with the following data structure:

credits
the number of non-expiring credits
freeCredits
the number of daily credits, where available
freeCreditsResetIn
the amount of time before the daily credits expire, where available

Account balance structure example (JSON)

{
    credits: 9633.516,
    freeCredits: 28.962,
    freeCreditsResetIn: '14:29:15'
}

Depending on their plans, certain Verifalia subscriptions may not come with free daily credits: in this case, the API returns only the number of non-expiring credits.

Example, using CURL

curl https://api.verifalia.com/v1.4/account-balance
    -u MyAccountSid:MyAuthToken

Latest tweets - twitter.com/verifalia

Monday, May 26, 2025

🚀 API v2.7 is finally here! Major updates include complete user management system, custom X.509 client certificates for mTLS, contact method management, 50+ fine-grained permissions in upgraded auth system, and much more. Check out the docs.

Tuesday, March 25, 2025

We are excited to announce our updated client area! Now featuring multiple administrators, personalized contact settings, enhanced permissions, and improved navigation: learn more.

Monday, February 3, 2025

Verifying Yahoo email addresses is now 40% faster! We've just updated our email verification algorithms for quicker results.

Wednesday, January 15, 2025

🎉 We've just launched version 1.13 of our free email verification widget, which Google Tag Manager (GTM) now supports. Plus, this new version brings support for custom trusted origins and SamCart! 🚀✨

From our blog

Introducing Verifalia API v2.7: Powerful Team Management Features for Developers

May 27, 2025

Verifalia API v2.7 introduces 14 new endpoints for automated user management and over 50 granular permissions, making it ideal for enterprise integrations and reseller solutions that need advanced user control.

New Client Area Enhancements: Multiple Administrators, Fine-Grained Permissions, and More

March 25, 2025

The latest version of our client area includes several new features designed to enhance our email verification service and simplify its use: this blog post highlights the key updates.

New Feature: Detection of Disposable Gmail and Outlook Mailboxes

October 22, 2024

Disposable or temporary Gmail and Outlook addresses may appear legitimate, but they should be removed from your mailing lists because they lead to fake registrations and false engagement.

Not a software developer?

Using the Verifalia API

Authentication

Data interchange format

API endpoints (base URLs)

Single base URL

Endpoints security

API limits

HTTP status codes

Email validations

Submitting a new validation

Request structure example (JSON)

Example, using CURL

Getting validation results

Example, using CURL

Result snapshot

Shorthand status properties for the status property:

Email validation structure example (JSON)

Validation status codes

Generic status codes

Syntax status codes

Disposable status codes

DNS status codes

SMTP status codes

Mailbox status codes

Catch-all status codes

Duplicates removal / scrub status codes

Miscellaneous status codes

Deleting an email validation job

Example, using CURL

Account

Account balance

Account balance structure example (JSON)

Example, using CURL

Latest tweets - twitter.com/verifalia

From our blog

Shorthand status properties for the `status` property: