Email Address Verification & List Cleaning & Validation API Documents

Sign Up

Login

Verify Email List

When you have a list of emails to be verified, it can be verified either by uploading a list from the client area, or use this API to upload and verify the email list. All you need to verify email list over API is an API key and a list of emails to be verified.

Once the email list is uploaded using this API, you can poll Check Job Status request to check the progress and status of email list verification. Upon completion, a comprehensive verification report for each email of the list is generated which can be downloaded from given download url. Optionally, you can set a callback url, QuickEmailVerification will send an automated notification(POST request) when the verification process is completed.


The Free API usage is limited to single email verification only. Bulk email verification API is available as paid service.

Preparing email list

QuickEmailVerification supports comma separated value (CSV) file uploads in various file types. If your csv file contains multiple column data along with email data column, all columns will be kept intact in the final verification report generated. To prepare csv list of email, please refer Supported File Formats. For any file that does not fit with the required format, a "400 Bad Request" will be returned.

API endpoint

POST https://api.quickemailverification.com/v1/bulk-verify

Request parameters

Below is a list of parameters available for this API endpoint :

apikeystringRequiredYour secret API key to authenticate the request. For example,
Authorization: token <YOUR_APIKEY>
filestringRequiredFile path of email address list to be verified.
X-QEV-FilenamestringOptionalAny valid name you'd like to assign to the file being uploaded. When not provided, the name of the uploaded file will be kept as it is.
X-QEV-CallbackstringOptionalA valid url to which API response will be posted as POST data once the verification process is completed. More info about callback data can be found later in this doc.

Example request and response

To verify email list, a request should be made as follows :

curl -X POST -F 'upload=@/home/user/email_list.csv' 'https://api.quickemailverification.com/v1/bulk-verify' \
    -H 'Authorization:token 94msdf823ns8234fdm23004m380234s242i9smkm234s0934m23402342901' \
    -H 'X-QEV-Filename:email_list.csv' \
    -H 'X-QEV-Callback:http://www.yoursite.com/qev-callback'

Which should respond something like :

{
    "id":"7138f61de8da380c345374c08bd64599",
    "success":true,
    "message":""
}

Once the list is uploaded, status of the verification can be checked by making the Check Job Status request using the returned id.


The 'id' returned in the response is important to make further requests to check the job status. Thus it should be saved.

Understanding HTTP response codes

When a Verify Email List request made does not fulfill the required criteria, it may fail returning a specific error code. While HTTP response code states the error in short, the "message" field of API response body contains a human readable description about the error. Below are some glossary of common error messages.

  • 400 Bad Request - The most likely reason for this can be, request made is missing mandatory parameters or provided file does not conform to supported criteria. Check the error message returned in the response to trace the error more closely. Additionally, you can view this guide to know how to solve such errors.

  • 402 Payment required - Credit balance in the account is not sufficient to complete the verification of uploaded file. Please purchase more credits to verify the email list.


Every email list uploaded using this API will count the required credits immediately and so we recommend to use small a list while development testing to prevent unnecessary draining of verification credits.

Response data posting to Callback url

If callback url is provided, an HTTP POST notification containing details about the verification result will be sent. Along with other summary, download urls for different reports are also included. Following is the schema of data posted to callback url.

id string Id assigned to uploaded email list
filename string Name of the uploaded file along with file extension
status string Status of the verification process. Like,
completed
running
failed
created_date string Date and time when file was uploaded to QuickEmailVerification
started_date string Date and time when the actual verification process started for the uploaded file
completed_date string Date and time when the verification process completed for the uploaded file
processing_time number Time taken to process the file (in seconds)
stats array Detailed statistics of the verification result. It contains following information,

total_email number total number of emails to be processed from the file
progress string Percentage of the verification process completion
result_counts array Counts of verification result, as following. Discover more about result terminologies here.

safetosend - number
valid - number
invalid - number
unknown - number
download_urls array The list of download url for verification reports as stated below. Append removeDuplicate=1 as an extra query string parameter to the download url if you want to exclude duplicate emails from the downloaded verification report.

safetosend string URL to download the list of just safe to send(recommended) emails
valid string Url to download the list of all valid emails
invalid string Url to download the list of just invalid emails
unknown string Url to download the list of just unknown emails
fullreport string Url to download complete report including every email

Following is the example of data posted to callback url.

Response Example

{
    "id": "7138f61de8da380c345374c08bd64599",
    "filename": "email_list.csv",
    "status": "completed",
    "created_date": "2017-08-18T04:06:08.000Z",
    "started_date": "2017-08-18T04:06:08.000Z",
    "completed_date": "2017-08-18T04:06:45.000Z",
    "processing_time": 37,
    "stats": {
        "total_email": 100,
        "progress": "100%",
        "result_counts": {
            "safetosend": 68,
            "valid": 82,
            "invalid": 16,
            "unknown": 2
        }
    },
    "download_urls": {
        "safetosend": "https://api.quickemailverification.com/v1/bulk-verify/download/safetosend/7138f61de8da380c345374c08bd64599?apikey=94msdf823ns8234fdm23004m380234s242i9smkm234s0934m23402342901",
        "valid": "https://api.quickemailverification.com/v1/bulk-verify/download/valid/7138f61de8da380c345374c08bd64599?apikey=94msdf823ns8234fdm23004m380234s242i9smkm234s0934m23402342901",
        "invalid": "https://api.quickemailverification.com/v1/bulk-verify/download/invalid/7138f61de8da380c345374c08bd64599?apikey=94msdf823ns8234fdm23004m380234s242i9smkm234s0934m23402342901",
        "unknown": "https://api.quickemailverification.com/v1/bulk-verify/download/unknown/7138f61de8da380c345374c08bd64599?apikey=94msdf823ns8234fdm23004m380234s242i9smkm234s0934m23402342901",
        "fullreport": "https://api.quickemailverification.com/v1/bulk-verify/download/fullreport/7138f61de8da380c345374c08bd64599?apikey=94msdf823ns8234fdm23004m380234s242i9smkm234s0934m23402342901"
    },
    "success": true,
    "message": ""
}

Data posting is considered successful if callback url returns 2XX HTTP response. If callback url is unresponsive during initial reporting or if it's not able to connect successfully, 3 retries will be made at certain interval. If callback url fails to return 2XX during retry, it will be considered fail and discarded for further attempt.