Bulk Email Validation API Guide - Beta

The Bulk Email Validation API allows you to submit requests containing up to 100,000 emails to be validated. This process happens asynchronously, allowing you to submit a job and retrieve it later once it has finished processing.

The service will inform you whether the emails addresses are valid or invalid, and provide additional information to offer further clarity. For a full list of statuses that can be returned and their implications, please see the tables later on in this guide.

Please note that this service is hosted in the United States.

In this guide we will:

• Explain how to make requests to the Bulk Email Validation API using three endpoints:
  • Submit: first, submit a list of emails for validation
  • Status: next, check the status of your submission
  • Retrieve: lastly, retrieve the results of your validation
• Provide a list of possible errors
• Offer best practice advice to help you make the most of this API 

Prerequisites

Before you start, make sure you have a Loqate account. If you don't already have one, you will need to sign up here.

You will also need a valid API key for use with the Bulk Email Validation service. We recommend you create a new API key, rather than repurposing an existing Email Validation key.

Use the instructions in this Quick Setup Guide to create a new Email Validation key:

• Follow the steps under the Adding the Loqate Tag to your site and Email Validation sections.
• You can use the Settings options to customise your key if you want, but none of those options should be necessary.

Best Practice and Guidance

Follow these guidelines to ensure your submissions are processed quickly and efficiently:

• Please limit the number of emails you submit per job to 100,000 or less (if you include more than this limit you will get an error)
• We recommend organising your lists so that you have a small number of large lists rather than lots of smaller lists
  • It is more beneficial to combine lists locally and submit as a single job rather than submitting each chunk of data separately
• We also recommend uploading one list at a time as uploading multiple lists will impact your processing speed. It is generally best to wait for one job to finish before uploading another
• If your list contains duplicates, each will be counted as an individual validation

Some other things to consider before making any submissions:

• Your account will be charged when you submit a job to us. If there are any issues in the processing of your job, we will credit back to your account where applicable
• Jobs will be stored for retrieval for up to 7 days before being deleted from our system. Please make sure you retrieve them within this time period, or you risk losing your results
• Keep your API key(s) safe. We suggest using separate API key(s) for this service and not to hardcode them into front end code where they can be scraped by a bad actor

Submitting a request

Start the process by submitting your list of emails in a JSON format, using a POST request to the Submit endpoint.

We have included example requests for all three endpoints, which you can use by swapping out the placeholders for your own API key and a selection of email addresses. We recommend you include at least one valid email address and at least one invalid email address, so that you can see the different statuses when using the Retrieve endpoint.

Example request:

POST https://api.addressy.com/EmailValidation/Bulk/Submit/v1.00/json4.ws
Header: Content-Type=application/json
{
    "Key": "<Key>",
    "Emails" : ["<validemail@example.com>", "<invalidemail@example.com>"]
}

Example response:

{    
  "ListId": "46361a42-55fe-4983-8c29-489297e40033",
  "ListState": "Pending"  
}

Please keep note of the ListID generated in the response, as this will be needed for all calls to the Status and Retrieve endpoints.

Checking the status of a job

Once your job has been uploaded and you have your listID, you are then able to check the status of your job by making a GET request to the Status endpoint.

Example request:

GET https://api.addressy.com/EmailValidation/Bulk/Status/v1.00/json4.ws?key=<key>&listid=<list-id>
{
    "Key": "<Key>",
    "ListID": "<ListID>"
}

Example response:

{
    "ListID": "46361a42-55fe-4983-8c29-489297e40033",
    "ListState": "Complete",
    "TotalVerifiedEmails": 2
}

Note that TotalVerifiedEmails shows the number of emails which have been verified so far, providing an indicator of the current status of your request (this updates every minute). This doesn't reflect the number that will be returned as valid in the Retrieve response.

Please see the following table for potential list states and their meaning. This endpoint should be polled until it returns a Complete ListState.

List States

Here are the list states you can receive when polling the status endpoint:

List State	Description
Pending	Job has been submitted but not started yet
Verifying	Job is in progress
Complete	Job has been completed and is ready for retrieval
Failed	Job has failed due to an error. Credit will be applied to your account where relevant

Retrieving your results

Once a Complete ListState has been returned, your job is ready for retrieval by making a GET request to the Retrieve endpoint.

Example request:

GET https://api.addressy.com/EmailValidation/Bulk/Retrieve/v1.00/json4.ws?key=<key>&listid=<list-id>
{
    "Key": "<Key>",
    "ListID" : "<ListID>"
}

Example response:

{
  "ListId": "46361a42-55fe-4983-8c29-489297e40033",
  "ListState": "Complete",
"TotalEmailCount": 2,
"Results": [
  {
      "Email": "validemail@example.com",
      "Status": "valid",
      "StatusMessage": "role_address"
      "Account": "validemail",
      "Domain": "example.com"
  },
      {
      "Email": "invalidemail@example.com",
      "Status": "invalid",
      "StatusMessage": "email_domain_invalid"
      "Account": "validemail",
      "Domain": "example.com"
     }
]
}

Result Fields

Your result for each email will be made up of the below fields.

Field	Description
Email	The email address you have sent to us for validation
Status	The status of the validation. Please see the below section for further information on possible statuses
StatusMessage	Additional information about the Status. Please see the below section for further information on possible status messages
Account	The account portion of the email address sent to us for validation
Domain	The domain portion of the email address you have sent to us for validation

Statuses

The results of your job will return a Primary Status (Status) and a Secondary Status (StatusMessage) per email. The following tables show the various potential statuses that might be returned.

Primary Status

Status	Description
valid	Email address is a valid account
invalid	Email address is invalid, refer to secondary statuses below for more information
accept_all	Indicates that the domain always says their emails are valid, even if they are not. This may be due to a firewall or another spam tool that can remove the message or send a bounce message later
unknown	The email address looks valid, but the domain is not responding. This could be a temporary issue if the domain is having problems, a dead domain, or due to a company firewall blocking access

 

Status Message

By default the StatusMessage will return as a blank field unless there is additional information to display.

StatusMessage	Description
email_address_invalid	The email address format is incorrect
email_domain_invalid	The email address is associated with a domain that does not exist
email_account_invalid	The email account does not exist at the given domain
mailbox_full_invalid	The inbox for this account is full and cannot accepting incoming mail
disposable	The email address is disposable
role_address	The email address was created to support a function such as support@, sales@ etc. This may be a valid email but typically underperforms compared to individual addresses

Errors

The table below lists the errors which exist for each of the API endpoints above.

For a list of errors applicable to all APIs, have a look at the list of common errors.

ID	Error	Cause	Resolution	Endpoint(s)
1001	NoDataSupplied	No emails have been supplied in the POST body of the request	Please ensure that your request contains emails for validation and try again	Submit
1002	TooManyEmailsSupplied	The count of emails exceeds 100,000	Please ensure that your request contains no more than 100,000 emails and try again	Submit
1003	InvalidListID	The given listID is not in the correct format or is not found in relation to your account	Ensure that your listID is correctly formatted and matches the one provided by our Submit endpoint	Status/Retrieve
1004	ExpiredListID	The given listID has expired due to a job being removed	Ensure that you retrieve your results within 7 days to avoid losing your job	Status/Retrieve
1006	MissingListID	A listID has not been given as part of the query parameters	Ensure that your request contains a listID and try again	Status/Retrieve
1007	JobInProgress	The job for the given listID is still in progress and cannot be retrieved	Ensure that you wait for your job to complete before retrieving and try again	Retrieve