Contact us

Bulk processing API documentation

Content

API usage rules

Number of emails
The maximum allowed number of emails is 50,000.
Result storing
The result is stored for 7 days.
Cost
1 credit per email

Making requests

POSThttps://emailverification.whoisxmlapi.com/api/bevService/

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

Content-Type
application/json

Create a new verification request

POSThttps://emailverification.whoisxmlapi.com/api/bevService/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

apiKey
Required. String.

Get your personal API KEY on My products page.
emails
Required. Array.

Contains array of email addresses for verification.
format
Optional. String.

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.
response
The response object.

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.
id
Integer.

Newly created verification request ID.
error
String.

Error description.
errors
Array.

Multiple error messages.

Get a list of your requests

POSThttps://emailverification.whoisxmlapi.com/api/bevService/request/list

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

apiKey
Required. String.

Get your personal API KEY on My products page.
page
Optional. Integer.

Used to paginate the result sets in conjunction with "perPage".

Default value: 1.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".
onlyIds
Optional. Boolean.

When it's true only the list of IDs is returned.

Default value: true.
perPage
Optional. Integer.

Limits each page of the result-set to this number of requests.

Min: 10; Max: 50.

Default value: 10
sort
Optional. String.

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.
response
The response object.

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.
data
Array.

A list of your requests' info elements (if "onlyIds" is true, each element has only the "id" field).
data[k].id
The response object.

Request ID.
data[k].date_start
String.

String representation of the request's start Unix timestamp.
data[k].total_emails
Integer.

The total of number of emails in the request.
data[k].invalid_emails
Integer.

Number of invalid emails.
data[k].processed_emails
Integer.

Number of already processed email addresses.
data[k].failed_emails
Integer.

Number of emails that could not be processed.
data[k].ready
Integer.

1 if processing has finished, 0 – otherwise.
from
Integer.

Min. request ID in the current page of the data set.
to
Integer.

Max. request ID in the current page of the data set.
per_page
Integer.

Max. number of requests for each page of the result set.
total
Integer.

The total number of requests in the result set.
current_page
Integer.

Current page number in the result set.
last_page
Integer.

The number of the last page in the set.
error
String.

Error description.
errors
Array.

Multiple error messages.

Get request's status

POSThttps://emailverification.whoisxmlapi.com/api/bevService/request/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

apiKey
Required. String.

Get your personal API KEY on My products page.
ids
Required. Array.

Required requests' IDs.
format
Optional. String.

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.
response
The response object.

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)

POSThttps://emailverification.whoisxmlapi.com/api/bevService/request/completed

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

apiKey
Required. String.

Get your personal API KEY on My products page.
id
Required. Integer.

ID of the request.
format
Optional. String.

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.
response
The response object.

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.
result
The result field may contains three values: "bad", "ok", "unknown". The "ok" value means that the email successful passed through the SMTP check, DNS check, and this email address isn’t disposable. The "bad" value means that some of this checks were failed. The "unknown" value means that email hosting supports "catch all feature".
emailAddress
The email address which was verified.
formatCheck
Equal to "false" when the given email has incorrect format.
smtpCheck
Checks does the email address exist and can receive messages or not? The value will be null if the SMTP request could not be completed, mailbox verification is not supported on the target mailbox provider, or not applicable.
dnsCheck
Ensures that the domain name part in the email address, eg: gmail.com, can be resolved via DNS. This value will be "true" if the domain is 'good' and "false" otherwise. May be "null" for invalid or non-existing emails.
freeCheck
Checks does the email host provide a free email addresses or not. This value will be "true" if it is possible to get email address for free, and 'false' otherwise. May be 'null' for invalid or non-existing emails.
disposableCheck
Checks does the email provider allows users to create temporary (disposable) email addresses (created via a service like Mailinator) or not. This may help you check for abuse. This value will be 'false' if the email is not disposable, and 'true' otherwise. May be 'null' for invalid or non-existing emails.
catchAllCheck
Tells you does this email address 'catch all' any emails for this domain or not. There is a special type of address that can receive email for any number of other addresses on the same host. This is common in businesses where if you send an email to support@example.com and another email to help@example.com, both of those emails will go into the same inbox. Possible values are 'true' or 'false'. May be 'null' for invalid or non-existing emails.
mxRecords
Mail servers list. May be absent for invalid or non-existing emails.

Get results (Invalid and failed emails)

POSThttps://emailverification.whoisxmlapi.com/api/bevService/request/failed

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

apiKey
Required. String.

Get your personal API KEY on My products page.
id
Required. Integer.

ID of the request.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".

List of possible errors

400 Bad Request
Some required fields are missing from the request's body or have invalid values.
401 Unauthorized
The required "apiKey" field value is missing or invalid.
402 Payment Required
Insufficient API queries account balance.
403 Forbidden
The request you're trying to access doesn't belong to your account.
422 Unprocessable Entity
The request you're trying to access doesn't belong to your account.
5XX
Internal server error, please contact our support team.

Try Email Verification API for free

Get started
Have questions?
support@whoisxmlapi.com
We will get back to you within a day.
WHOIS API, Inc.

California
USA

Contact us