Help

Running a Free Analysis

Our API allows you to run a free analysis to determine your overall list health.

PipelineAnchor

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

analysis_pipeline

Starting an AnalysisAnchor

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.

Example Request:

curl -X POST https://api.neverbounce.com/v3/bulk\
    -d access_token=<ACCESSTOKEN>\
    -d input_location=0\
    -d input=<URL>\
    -d filename=<FILENAME>\
    -d run_sample=1

Example Response:
{
    "success": true,
    "job_status": 0,
    "job_id": 22099,
    "execution_time": 0.16023087501526
}

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.

Checking the status of an AnalysisAnchor

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.

Example Request:

curl -X POST https://api.neverbounce.com/v3/status\
    -d access_token=<ACCESS TOKEN>\
    -d version=3.1\
    -d job_id=<JOB ID>

Example Response:
{
    "success": true,
    "id": "00000",
    "status": "1",
    "type": "0",
    "input_location": "1",
    "orig_name": "Filename",
    "stats": {
        "total": 256,
        "processed": 256,
        "valid": 0,
        "invalid": 0,
        "bad_syntax": 0,
        "catchall": 0,
        "disposable": 0,
        "unknown": 0,
        "duplicates": 0,
        "billable": 256,
        "job_time": 50
    },
    "created": "2016-02-08 15:31:18",
    "started": "2016-02-08 15:31:30",
    "finished": "2016-02-08 15:32:20",
    "file_details": "{\"error\":false,\"email_col_i\":0,\"tot_cols\":2,\"delimiter\":\",\",\"has_header\":false,\"size\":7902,\"tot_records\":257,\"tot_emails\":256}",
    "job_details": {
        "sample_status": 1
        }
    },
    "execution_time": 0.055294990539551
}

When polling an analysis you’ll want to pay attention to the sample_status parameter in the job_details object. The possible values for this parameter are listed below.

Analysis Status Codes

Value Definition
1 Waiting to start sampling
2 Sampling list
3 Sampling completed

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": "00000",
    "status": "2",
    "type": "0",
    "input_location": "1",
    "orig_name": "Filename",
    "stats": {
        "total": 256,
        "processed": 256,
        "valid": 0,
        "invalid": 0,
        "bad_syntax": 0,
        "catchall": 0,
        "disposable": 0,
        "unknown": 0,
        "duplicates": 0,
        "billable": 256,
        "job_time": 50
    },
    "created": "2016-02-08 15:31:18",
    "started": "2016-02-08 15:31:30",
    "finished": "2016-02-08 15:32:20",
    "file_details": "{\"error\":false,\"email_col_i\":0,\"tot_cols\":2,\"delimiter\":\",\",\"has_header\":false,\"size\":7902,\"tot_records\":257,\"tot_emails\":256}",
    "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,
                "t": 256,
                "p": 256,
                "g": 199,
                "b": 7,
                "c": 32,
                "d": 0,
                "u": 18
            },
            "bounce_estimate": 0.02734375
        }
    },
    "execution_time": 0.055294990539551
}

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.

Running Verification after an AnalysisAnchor

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>

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.