Format
Here's the format to call the Email Validation API:

Data Tool
This API accepts the following data tool:
Data Tool Value | Description |
emailValidation | enables to obtain a validation for the email used as input. |
Inputs - what the API uses to search
Inputs are information that the Email Validation API will use to search in the Versium REACH back end. This API service accepts a consumer first and last name, and any other known consumer contact information in Common API Parameters. It matches your inputs with consumers in the Versium Data store, and returns consumer information, as available.
value | description | example |
---|---|---|
A valid MD5 or SHA256 HEM | [email protected] |
*For Hashed input details, please visit the Developer Portal on <https://api-documentation.versium.com/reference/hashed-input-support>
The API will then match your inputs with consumers in the Versium Data store, and returns business information, as available.
Optional Parameters
At present, the Email Validation API accepts the following optional parameters.
name |
description |
value type |
possible values |
notes |
output[] |
Whether to include an alternate, valid email, in the output response, if the input email is invalid. |
string |
email_validation_alternate |
|
rcfg_exlude_domains[] |
A list of domains to not return alternate emails from. |
string - an email provider domain |
Like output[], this param uses bracket syntax, so a GET request would look like: |
|
rcfg_snake_case |
A boolean to tell the Versium API to return key names in snake case, instead of upper case with spaces. |
boolean |
1 |
Inside the “results” array: |
Optional search params - use with output[]=email_validation_alternate
These additional search parameters will help REACH find an alternative valid email if the input email address is invalid.
name | description | example |
---|---|---|
first | A person’s first name | John |
last | A person’s last name | Doe |
address | A house/building number and street | 123 Main St |
address_2 | The unit # of an address | Apt 12 or Unit 510 |
city | A city name | Seattle |
state | A US state or Canadian province two letter abbreviation | WA or BC |
zip | A 5 digit US ZIP code or Canadian Postal code | 98052 or V6Y-1H3 |
country | A 2 digit country code - only US is supported | US |
phone | A valid 10 digit North American phone number | 2061235555 |
Example queries
-
Validate an email only:
-
<https://api.versium.com/v2/>emailValidation?email=[[email protected]](mailto:[email protected])
-
Validate a HEM:
-
<https://api.versium.com/v2/>emailValidation?email=42a35e2648d4e1782cc3d1357d73bddd
-
Validate an email and return an alternate email if the input one is invalid:
-
<https://api.versium.com/v2/>emailValidation?output\[\]=email\_validation\_alternate&email=[[email protected]](mailto:[email protected])
-
Validate an email, return an alternate email if the input one is invalid, but don’t return any aol.com or
<http://yahoo.com>
alternate emails -
<https://api.versium.com/v2/>emailValidation?output\[\]=email\_validation\_alternate&email=[[email protected]](mailto:[email protected])&rcfg\_exclude\_domains\[\]=<http://aol.com> &rcfg\_exclude\_domains\[\]=<http://yahoo.com>
Response Structure
The api only supports returning json.
Successful response structure
{
"versium": {
"version":"2.0",
"match_counts":{},
"num_matches":0,
"num_results":0,
"query_id":"48f9238a-ba98-4c45-97df-74f405c97527",
"query_time":7.340619087219238,
"results":[{}],
"input_query":{}
}
}
Structure of record in “results”
Unless an error occurs, the email validation will always return the following fields, as part of an object, inside the “results” array:
name | value type | description | example |
---|---|---|---|
Email Address |
string |
The input “email” value if it is valid. |
|
Is Input Email Valid |
boolean |
A boolean indicating whether the input email is valid. |
true |
Is Alternate Email |
boolean |
A boolean indicating whether the value in the “Email Address” field is the original, input email, or an alternate, valid email supplied by Versium. |
false |
Email Validation Status |
string |
The primary validation status of the input email address. The possible values are: |
spamtrap |
Email Validation Sub-status |
string |
A secondary, more descriptive validation status: |
failed_syntax_check |
Status descriptions
- invalid - emails were determined to be invalid, please delete them from your mailing list.
- valid - emails were determined to be valid.
- unknown - emails were not validated for one reason or another.
- spamtrap - emails are believed to be spamtraps and should not be mailed.
- catch-all - emails are impossible to validate without sending a real email and waiting for a bounce.
- abuse - emails are of people who are known to click the abuse links in emails, therefore abusers or complainers.
- do_not_mail - emails are of companies, role-based, or people you just want to avoid emailing to.
Sub-status descriptions
- timeout_exceeded (Unknown) - These emails belong to a mail server that is responding extremely slow.
- failed_syntax_check (Invalid) - Emails that do not meet RFC syntax protocols
- global_suppression (do_not_mail) - These emails are found in many popular global suppression lists (GSL).
- no_dns_entries (Invalid)- These emails are valid in syntax, but the domain doesn't have any records in DNS or have incomplete DNS Records.
- mailbox_not_found (Invalid) - These emails addresses are valid in syntax, but do not exist.
- mailbox_quota_exceeded (Invalid) - These emails exceeded their space quota and are not accepting emails.
- does_not_accept_mail (Invalid) - These domains only send mail and don't accept it.
- toxic (do_not_email) - These email addresses are known to be abuse, spam, or bot created emails.
- possible_trap (do_not_email) - These are emails of commonly misspelled popular domains.
- exception_occurred (unknown) - These emails caused an exception when validating.
- disposable (do_not_email) - These are temporary emails created for the sole purpose to sign up to websites without giving their real email address. These emails are short lived from 15 minutes to around 6 months. There is only 2 values (True and False). If you have valid emails with this flag set to TRUE, you shouldn't email them.
- alias (Valid) - These emails addresses act as forwarders/aliases and are not real inboxes.
- greylisted (Unknown) - Emails where we are temporarily unable to validate them.
- mail_server_temporary_error (Unknown) - These emails belong to a mail server that is returning a temporary error.
- mail_server_did_not_respond (Unknown) - These emails belong to a mail server that is not responding to mail commands.
- forcible_disconnect (Unknown) - These emails belong to a mail server that disconnects immediately upon connecting.
- failed_smtp_connection (Unknown) - These emails belong to a mail server that won't allow an SMTP connection.
- role_based (do_not_email) - These emails belong to a position or a group of people, like sales@ info@ and contact@.
- unroutable_ip_address (Invalid) - These emails domains point to an un-routable IP address, these are marked invalid.
- domain_cant_receive_emails - The domain cannot received any email.
Successful response example
{
"versium": {
"version":"2.0",
"match\_counts":{
"email\_validation":1,
},
"num\_matches":1,
"num\_results":1,
"query\_id":"48f9238a-ba98-4c45-97df-74f405c97527",
"query\_time":7.340619087219238,
"results":\[
{
"Email Address": "[[email protected]](mailto:[email protected])",
"Is Input Email Valid": true,
"Email Validation Status": "valid",
"Email Validation Sub-status": "valid",
}
\],
"input\_query":{
"email":"[[email protected]](mailto:[email protected])"
}
}
}
Successful response example when using output[]=email_validation_alternate
{
"versium": {
"version": "2.0",
"match\_counts": {
"email\_validation": 1,
"email\_validation\_alternate": 1,
},
"num\_matches": 1,
"num\_results": 1,
"query\_id": "48f9238a-ba98-4c45-97df-74f405c97527",
"query\_time": 7.340619087219238,
"results": \[
{
"Email Address": "[[email protected]](mailto:[email protected])",
"Is Input Email Valid": false,
"Is Alternate Email": true,
"Email Validation Status": "spamtrap",
"Email Validation Sub-status": "possible\_trap",
}
\],
"input\_query": {
"email": "[[email protected]](mailto:[email protected])"
}
}
}
Error responses
When an error occurs, the response object will contain an “errors” property, which array of strings.
{
"versium": {
"version":"2.0",
"match\_counts":{},
"num\_matches":0,
"num\_results":0,
"query\_id":"48f9238a-ba98-4c45-97df-74f405c97527",
"query\_time":7.340619087219238,
"results":\[{}\],
"input\_query":{},
"errors": \[\]
}
}