Bulk processing API documentation
Content
API usage rules
Making requests
In order to check lists of emails with the Bulk API, first upload the emails to the server which will create a verification request and return its ID to you. Then you can use this ID to query the request's status, download results etc.
The API expects parameters to be JSON-encoded in the body of each request.
Headers
Create a new verification request
CURL request sample
curl https://emailverification.whoisxmlapi.com/api/bevService/request -X POST -H "Content-Type: application/json" -d '{"apiKey": "YOUR_API_KEY", "emails": ["alex@hotmail.edu", "bob@google.com", "mila@yahoo.com"], "format": "json"}'
POST request body sample
{
"apiKey": "YOUR_API_KEY",
"emails": [
"alex@hotmail.edu",
"bob@google.com",
"mila@yahoo.com"
],
"format": "json"
}
Input parameters
Contains array of email addresses for verification.
Used to specify the response format.
Allowed values: "xml", "json", "csv".
Default value: "json".
Sample output
{
"response": {
"id": 5
}
}
Code: 200 OK.
{
"response": {
"errors": [
"The format field should have one of the following values: json, xml."
]
}
}
Code: 400 Bad Request.
{
"response": {
"error": "Authorisation or authentication failed"
}
}
Code: 401 Unauthorized.
{
"response": {
"error": "Insufficient balance"
}
}
Code: 402 Payment Required.
Contains the integer "id" field on success.
In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.
Newly created verification request ID.
Error description.
Multiple error messages.
Get a list of your requests
CURL request sample
curl https://emailverification.whoisxmlapi.com/api/bevService/request/list -X POST -H "Content-Type: application/json" -d '{"apiKey": "YOUR_API_KEY", "page": 1, "onlyIds": false, "perPage": 10, "sort": "desc", "format": "json"}'
POST request body sample
{
"apiKey": "YOUR_API_KEY",
"page": 1,
"format": "json",
"onlyIds": false,
"perPage": 10,
"sort": "desc"
}
Input parameters
Used to paginate the result sets in conjunction with "perPage".
Default value: 1.
Used to specify the response format.
Allowed values: "xml", "json", "csv".
Default value: "json".
When it's true only the list of IDs is returned.
Default value: true.
Limits each page of the result-set to this number of requests.
Min: 10; Max: 50.
Default value: 10
Specify the order of requests in the response.
Allowed values: "asc", "desc".
Default value: "desc".
Sample output
{
"response": {
"current_page": 1,
"data": [
{
"id": 596
},
{
"id": 595
},
{
"id": 544
}
],
"from": 1,
"last_page": 1,
"per_page": 10,
"to": 3,
"total": 3
}
}
Code: 200 OK.
{
"response": {
"current_page": 1,
"data": [
{
"id": 596,
"date_start": "1528377253",
"total_emails": 3,
"invalid_emails": 0,
"processed_emails": 3,
"failed_emails": 0,
"ready": 1
},
{
"id": 595,
"date_start": "1528377227",
"total_emails": 20,
"invalid_emails": 0,
"processed_emails": 20,
"failed_emails": 0,
"ready": 1
},
{
"id": 544,
"date_start": "1528204702",
"total_emails": 500,
"invalid_emails": 0,
"processed_emails": 500,
"failed_emails": 0,
"ready": 1
}
],
"from": 1,
"last_page": 1,
"per_page": 10,
"to": 3,
"total": 3
}
}
Code: 200 OK.
Contains the "data" field with an array of user's requests' data on success.
The "from" and "to" fields represent the result set's ID range of the requests returned for the current page.
"per_page" is the pages' size and "total" is the number of requests in the result set.
The "current_page" and "last_page" correspond to the number of pages in the result set.
In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.
A list of your requests' info elements (if "onlyIds" is true, each element has only the "id" field).
Request ID.
String representation of the request's start Unix timestamp.
The total of number of emails in the request.
Number of invalid emails.
Number of already processed email addresses.
Number of emails that could not be processed.
1 if processing has finished, 0 – otherwise.
Min. request ID in the current page of the data set.
Max. request ID in the current page of the data set.
Max. number of requests for each page of the result set.
The total number of requests in the result set.
Current page number in the result set.
The number of the last page in the set.
Error description.
Multiple error messages.
Get request's status
CURL request sample
curl https://emailverification.whoisxmlapi.com/api/bevService/request/status -X POST -H "Content-Type: application/json" -d '{"apiKey": "YOUR_API_KEY", "ids": [622], "format": "json"}'
POST request body sample
{
"apiKey": "YOUR_API_KEY",
"ids": [544, 595, 596],
"format": "json"
}
Input parameters
Required requests' IDs.
Used to specify the response format.
Allowed values: "xml", "json", "csv".
Default value: "json".
Sample output
{
"response": [
{
"id": 544,
"date_start": "1528204702",
"total_emails": 500,
"invalid_emails": 0,
"processed_emails": 500,
"failed_emails": 0,
"ready": 1
},
{
"id": 595,
"date_start": "1528377227",
"total_emails": 20,
"invalid_emails": 0,
"processed_emails": 20,
"failed_emails": 0,
"ready": 1
},
{
"id": 596,
"date_start": "1528377253",
"total_emails": 3,
"invalid_emails": 0,
"processed_emails": 3,
"failed_emails": 0,
"ready": 1
}
]
}
Code: 200 OK.
Contains an array of user's requests' info on success. This array can be empty in case the "ids" array contains non-existing ids only.
In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.
Get results (processed emails)
CURL request sample
curl https://emailverification.whoisxmlapi.com/api/bevService/request/completed -X POST -H "Content-Type: application/json" -d '{"apiKey": "YOUR_API_KEY", "id": 622, "format": "json"}'
POST request body sample
{
"apiKey": "YOUR_API_KEY",
"id": 596,
"format": "csv"
}
Input parameters
ID of the request.
Used to specify the response format.
Allowed values: "xml", "json", "csv".
Default value: "json".
Sample output
{
"response": [
{
"emailAddress": "alex@alex.edu",
"formatCheck": "true",
"smtpCheck": "null",
"dnsCheck": "false",
"freeCheck": "false",
"disposableCheck": "false",
"catchAllCheck": "null",
"result": "bad"
},
{
"emailAddress": "bob@google.com",
"formatCheck": "true",
"smtpCheck": "true",
"dnsCheck": "true",
"freeCheck": "false",
"disposableCheck": "false",
"catchAllCheck": "true",
"mxRecords": [
"alt2.aspmx.l.google.com",
"alt3.aspmx.l.google.com",
"alt4.aspmx.l.google.com",
"aspmx.l.google.com",
"alt1.aspmx.l.google.com"
],
"result": "unknown"
},
{
"emailAddress": "mila@yahoo.com",
"formatCheck": "true",
"smtpCheck": "true",
"dnsCheck": "true",
"freeCheck": "true",
"disposableCheck": "false",
"catchAllCheck": "true",
"mxRecords": [
"mta6.am0.yahoodns.net",
"mta5.am0.yahoodns.net",
"mta7.am0.yahoodns.net"
],
"result": "unknown"
}
]
}
Code: 200 OK.
{
"response": {
"error": "Wrong request id"
}
}
Code: 422 Unprocessable Entity.
Contains an array of verification results for each email address in the original request (see the documentation below).
Responses to these request can be saved directly to disk.
In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.
Get results (Invalid and failed emails)
CURL request sample
curl https://emailverification.whoisxmlapi.com/api/bevService/request/failed -X POST -H "Content-Type: application/json" -d '{"apiKey": "YOUR_API_KEY", "id": 622, "format": "json"}'
POST request body sample
{
"apiKey": "YOUR_API_KEY",
"id": 596,
"format": "csv"
}
Input parameters
ID of the request.
Used to specify the response format.
Allowed values: "xml", "json", "csv".
Default value: "json".
List of possible errors
Try Email Verification API for free
Have questions?
We work hard to improve our services for you. As part of that, we welcome your feedback, questions and suggestions. Please let us know your thoughts and feelings, and any way in which you think we can improve our product.
For a quick response, please select the request type that best suits your needs. For more info regarding the request types, see the Contact us page.