Once the email list is uploaded for verification using Verify Email List, you may need to check its verification status using this API.

To retrieve its current status, make a GET request of status API using the id returned in the response of the Verify Email List API. If the callback url was provided while uploading the file for verification, QuickEmailVerification will send the complete result as a POST notification to the callback url as soon as verification is completed. In that case, you may not need to poll the requests to check the status of the uploaded job.

API endpoint

GET https://api.quickemailverification.com/v1/bulk-verify/status/{job_id}

Request parameters

The below given parameter is required for this API endpoint. Along with apikey query string parameter, id is passed as the path parameter to this API. This id is returned when the email list is uploaded to QuickEmailVerification using Verify Email List.

apikeystringRequiredYour secret API key

Example request and response

When you have job ID, you can check its status like following,

curl --get --include "https://api.quickemailverification.com/v1/bulk-verify/status/7138f61de8da380c345374c08bd64599?apikey=94msdf823ns8234fdm23004m380234s242i9smkm234s0934m23402342901"

Which may yield response like below :

{
    "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": ""
}

When job status check request does not retrieve successful response, the message field will help you find more info about the probable issues. It contains descriptive info about the problem. Along with that, HTTP response code for every request has important information about the success of API request. To be familiar with possible HTTP response codes QuickEmailVerification API endpoints may return, visit Kick Start with Email Verification API.

API response schema

The API response schema is explained below.

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
ready
created_date string Date and time when file 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 the following information,

total_email number total number of email to be processed from the file
progress string Percentage of verification process completion. When job status is running, this field helps to know how long the verification process has been reached. When verification is completed this would contain 100%.
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
success boolean Describes success of job status
true - successful
false - error occurred
message string Human readable message describing the error generated for this email list (if any).

Understanding different job status

Which stage the uploaded email list is going through can be found inside the status field of the job status check response. Some important status values are discussed below.

  • failed - For every list uploaded, QuickEmailVerification performs detailed scanning on the list prior to take it up for verification. If the email list fails during this scanning phase, failed status will be set for that email list. To fix and debug this type of jobs, you can check the message returned in the message field of response.

  • running - Verification process for the uploaded email list is ongoing. The percentage of process completion can be found in the progress field of the response.

  • completed - This indicates that the verification process is completed and verification reports are ready to be downloaded. To download the reports, check download_urls which contains the download urls for each report. Please note, these urls are populated only for the jobs which have been completed.

  • ready - A ready status in the API response means your account has insufficient credits to start the job. All you need to do is login to your account and purchase the required credits. Once credits are added in your account, you can manually start that job from your dashboard.

Status check request polling

The interval of polling status check requests highly depends on the size of the email list. For a smaller list, few status check requests at a small gap of time will be sufficient. While for larger lists, interval should be increased accordingly. For example, if the email list contains just a few hundred emails like 400 or 500 emails, the polling interval of 5 minutes is considered good. But if the email list has more than 1 lac emails, we recommend to keep minimum 15 - 20 minute gap between two status check requests.