• Developers
• /
• APIs
• /
• Email Validation

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

Note: we don't support API connections using HTTP - all calls should use HTTPS.

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:

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.

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 Message

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

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.