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:
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 these guidelines to ensure your submissions are processed quickly and efficiently:
Some other things to consider before making any submissions:
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.
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.
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 |
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" } ] }
Your result for each email will be made up of the below fields.
Field | Description |
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 |
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.
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 |
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 |
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 |