Email Validation API

Format

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

Data Tool

This API accepts the following data tool:

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.

*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.

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.

Example queries

1. Validate an email only:

   1. https://api.versium.com/v2/emailValidation?email=[email protected]

2. Validate a HEM:

   1. https://api.versium.com/v2/emailValidation?email=42a35e2648d4e1782cc3d1357d73bddd

3. Validate an email and return an alternate email if the input one is invalid:

   1. https://api.versium.com/v2/emailValidation?output[]=email_validation_alternate&email=[email protected]

4. 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

   1. https://api.versium.com/v2/emailValidation?output[]=email_validation_alternate&email=[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:

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": \[\]  
  }  
}