Bulk Email Validation

The Bulk Email Validation API allows you to submit requests containing up to 100,000 emails to be validated. This process happens asynchronously using three endpoints, 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 Bulk Email Validation API documentation.

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
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 the Tag 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.

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. Note: we don’t support API connections using HTTP - all calls should use HTTPS.

Example Submit 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 Submit 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 Status request:

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

{
    "Key": "Key",
    "ListID": "ListID"
}

Example Status 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. Keep polling this endpoint until it returns a Complete ListState. Here are the possible 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"
     }
]
}

Results

Your result for each email will be made up of the following 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

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

Get Started

Our Products

Integrations

Bulk Email Validation

Prerequisites

Submitting a request

Example Submit request:

Example Submit response:

Checking the status of a job

Example Status request:

Example Status response:

Retrieving your results

Example request:

Example response:

Results

Statuses

Best Practice and Guidance

Get Started

Our Products

Integrations

​Prerequisites

​Submitting a request

​Example Submit request:

​Example Submit response:

​Checking the status of a job

​Example Status request:

​Example Status response:

​Retrieving your results

​Example request:

​Example response:

​Results

​Statuses

​Best Practice and Guidance

Prerequisites

Submitting a request

Example Submit request:

Example Submit response:

Checking the status of a job

Example Status request:

Example Status response:

Retrieving your results

Example request:

Example response:

Results

Statuses

Best Practice and Guidance