Running a Free Analysis
This version has been depreciated
Existing integrations using this API will continue to work as usual. However, new integrations should be created using the V4 API. We will continue to support this API for the foreseeable future but will not be adding new features to it.
Our API allows you to run a free analysis to determine your overall list health.
The Pipeline
Analyzing a list through the API works the same way it does in the dashboard. Once submitted, your list will be indexed and deduped, followed by the analysis process. The analysis will take a few minutes to complete, so the results will not be returned immediately. You will need to periodically poll the API to check on the status of the analysis until it has completed. Once complete, you will get an estimated bounce rate for your list. From this you can decide whether or not you want to verify the entire list. Below is a flowchart illustrating this pipeline.
A flowchart showing the process of running an analysis
1. Starting an Analysis
Before starting an analysis, read over how to add a list. You’ll use the same request to start your analysis with the addition of the run_sample parameter with a value of 1. This extra parameter will tell the API to only analyze the list for now.
curl -X POST https://api.neverbounce.com/v3/bulk\
-d access_token={access_token}\
-d input_location=0\
-d input={url}\
-d run_sample=1
Unsure where to get an
access_token? Click here to find out how to generate one.
Read more about the
bulkendpoint here.
{
"success": true,
"job_id": 194459,
"job_status": 0,
"job_file": "2017-04-26.api_job.1054.590102fbcae30.csv",
"execution_time": 0.60870909690857
}
Once you get a response, you’ll want to store the value of job_id, as it will be used to check the status of the analysis.
2. Checking the status of an Analysis
At this point, you’ll need to start polling the API to know when the analysis has completed. Typically, an analysis will only take a few minutes, so polling at a 5-10 second interval will work fine.
curl -X POST https://api.neverbounce.com/v3/status\
-d access_token={access_token}\
-d version=3.1\
-d job_id={job_id}
Read more about the
statusendpoint here.
{
"success": true,
"id": "194459",
"status": "4",
"type": "1",
"input_location": "1",
"orig_name": "2017-04-26.api_job.1054.590102fbcae30.csv",
"stats": {
"total": 256,
"processed": 1,
"valid": 1,
"invalid": 0,
"catchall": 0,
"disposable": 0,
"unknown": 0,
"duplicates": 0,
"bad_syntax": 0,
"billable": 256,
"job_time": 0
},
"created": "2017-04-26 16:28:43",
"started": "2017-04-26 16:28:40",
"finished": "2017-04-26 16:28:40",
"analysis_started": null,
"analysis_finished": null,
"indexing_started": "2017-04-26 16:28:44",
"indexing_finished": "2017-04-26 16:28:44",
"last_touched": "2017-04-26 16:28:40",
"file_details": "{\"error\":false,\"email_col_i\":0,\"tot_cols\":1,\"delimiter\":\"\",\"has_header\":false,\"linefeed_type\":\"LINEFEED_0A\",\"quote_type\":\"QUOTE_DOUBLE\",\"delimiter_type\":\"DELIM_COMMA\",\"binary_options_type\":\"BIN_1_0\",\"size\":20,\"tot_records\":2,\"tot_emails\":0}",
"job_details": {
"sample_status": 1
}
},
"execution_time": 0.012382984161377
}
When polling an analysis, you will want to pay attention to the sample_status parameter in the job_details object.
Once the sample_status value is 3, the analysis has completed and you’ll find a sample_details object and bounce_estimate parameter in the job_details object in the response now as well.
{
"success": true,
"id": "194459",
"status": "4",
"type": "1",
"input_location": "1",
"orig_name": "2017-04-26.api_job.1054.590102fbcae30.csv",
"stats": {
"total": 256,
"processed": 256,
"valid": 199,
"invalid": 7,
"bad_syntax": 0,
"catchall": 32,
"disposable": 0,
"unknown": 18,
"duplicates": 0,
"billable": 256,
"job_time": 0
},
"created": "2017-04-26 16:28:43",
"started": "2017-04-26 16:28:40",
"finished": "2017-04-26 16:28:40",
"analysis_started": null,
"analysis_finished": null,
"indexing_started": "2017-04-26 16:28:44",
"indexing_finished": "2017-04-26 16:28:44",
"last_touched": "2017-04-26 16:28:40",
"file_details": "{\"error\":false,\"email_col_i\":0,\"tot_cols\":1,\"delimiter\":\"\",\"has_header\":false,\"linefeed_type\":\"LINEFEED_0A\",\"quote_type\":\"QUOTE_DOUBLE\",\"delimiter_type\":\"DELIM_COMMA\",\"binary_options_type\":\"BIN_1_0\",\"size\":20,\"tot_records\":2,\"tot_emails\":0}",
"job_details": {
"sample_status": 3,
"sample_details": {
"sample_size": 256,
"sample_stats": {
"total": 256,
"processed": 256,
"valid": 199,
"invalid": 7,
"bad_syntax": 0,
"catchall": 32,
"disposable": 0,
"unknown": 18,
"duplicates": 0,
"billable": 256,
"percent_complete": 100
},
"bounce_estimate": 0.02734375
}
},
"execution_time": 0.012382984161377
}
The bounce_estimate parameter will give you a good idea of your lists’ overall health. This is the percentage 0.00 – 1.00 we estimate your list will bounce at. Depending on how high the bounce_estimate is, you may want to run full verification on the list. Our suggestion is anything under 0.02 is typically safe to send while anything between 0.02 to 0.08 may need verification depending on your sender, and anything over 0.08 should always be verified.
4. Running Verification after an Analysis (Optional)
If you decide full verification is necessary, you can use the following request.
curl -X POST https://api.neverbounce.com/v3/start_job\
-d access_token={access_token}\
-d job_id={job_id}
Read more about the
start_jobendpoint here.
Now your list has begun the verification process. At this point, you’ll want to rely on the verfying a list pipeline, skipping the “Adding a List” step. Keep in mind the job_id will remain the same.
Updated about 7 years ago