Running a Free Analysis

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 as 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.

1. Starting an Analysis

Before starting an analysis, read over how to add a list. You’ll use the same requests with the addition of the run_sample parameter. Below, you'll see an example of creating a job and running an analysis with a remote URL.

curl --request POST\
  --url https://api.neverbounce.com/v4/jobs/create\
  --data key={api_key}\
  --data input_location='remote_url'\
  --data filename='SampleNeverBounceAPI.csv'\
  --data auto_parse=1\
  --data auto_start=1\
  --data run_sample=1\
  --data input='https://mydomain.com/my_file.csv'

📘

Read more about the bulk endpoint here.

{
  "status": "success",
  "job_id": 150970,
  "execution_time": 712
}

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 --request GET\
  --url 'https://api.neverbounce.com/v4/jobs/status?key={api_key}&job_id={job_id}'

📘

Read more about the status endpoint here.

{
    "status": "success",
    "id": 185137,
    "filename": "NBUser_1054_58f2b406006f1",
    "created": "2017-04-15 20:00:06",
    "started": "2017-04-15 20:00:21",
    "finished": "2017-04-15 21:52:46",
    "total_records": 24606,
    "total_billable": 24606,
    "total_processed": 24606,
    "total_valid": 18227,
    "total_invalid": 1305,
    "total_catchall": 4342,
    "total_disposable": 16,
    "total_unknown": 716,
    "total_duplicates": 0,
    "total_bad_syntax": 0,
    "bounce_estimate": 5.3035844915874,
    "percent_complete": 100,
    "job_status": "waiting_analyzed",
    "execution_time": 2535
}

When polling an analysis, you’ll want to pay attention to the job_status parameter. Once the job_status value is waiting_analyzed, the analysis has completed and you can get the estimated bounce rate from bounce_estimate.

The bounce_estimate parameter will give you a good idea of your lists’ overall health. This is the percentage 0.0-100.0 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 2.0 is typically safe to send while anything between 2.0 to 8.0 may need verification, depending on your sender, and anything over 8.0 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 --request POST\
  --url https://api.neverbounce.com/v4/jobs/start\
  --data key={api_key}\
  --data job_id={job_id}

📘

Read more about the start endpoint 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.