Loqate, a GBG solution
Loqate

Help Centre   |   Guides   |   Address, Email and Phone Verification   |   Bulk Email Validation API Guide - Beta

Bulk Email Validation API Guide - Beta

This product version is currently available as a Beta release. Whilst in Beta we reserve the right to make changes to our APIs. We would value your feedback; please use the widget on the page to do this.

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
Sign up for a free trial or book a demo Get started