Getting Started

 

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.

The NeverBounce API is a common RESTful API. All requests are performed via an HTTPS connection and responses are returned as JSON. This widely-accepted format allows for easy use with the most common programming languages and development kits while remaining portable, expandable, and secure.

Below you will find a description of the various endpoints, the parameters they accept, and the responses they send.

Use in the browser

This version of the API is not suitable for use in client-side scripts (e.g. jQuery, Javascript). Using it on the client-side would require exposing sensitive API credentials; giving anyone access to your account.

Authentication

 

Version 3 of our API utilizes the popular OAuth 2.0 authentication model. This requires you to make an initial request for an access_token before making other API requests. To do this you will need to use your account's API Username and API Secret Key found here.

/access_token

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.neverbounce.com/v3/access_token
curl -X POST -u {api_username}:{api_secret_key} https://api.neverbounce.com/v3/access_token\
    -d grant_type=client_credentials\
    -d scope=basic+user
A binary file was returned

You couldn't be authenticated

{
    "access_token":"4d277ec7686b1372af1cd8a428cc457553039db2",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":"basic user"
}

Form Data

grant_type
string
required

Accepted value is: 'client_credentials'

scope
string
required

Accepted value is: 'basic user'

 

Error Handling

 

Authorization Errors

When requesting an access_token is unsuccessful, you’ll receive a response containing an error and error_description parameter.

{
    "error": "invalid_request",
    "error_description": "The grant type was not specified in the request"
}

Codes:

  • invalid_client: The api username and/or api secret key is incorrect.
  • invalid_request: The request is missing a required parameter. Verify that you are passing the grant_type and scope parameters.
  • unsupported_grant_type: The grant type you’ve supplied is unsupported. Make sure you are passing in client_credentials as the grant type.
  • invalid_scope: The scope supplied is unsupported. Make sure you’ve supplied basic user as the scope.

Expired/Invalid Access Tokens

When an access_token expires or is invalid, you’ll receive the following response:

{
    "success": false,
    "msg": "Authentication failed"
}

API Errors

When an API request is unsuccessful, you’ll receive an error message containing a success parameter set to false. When this happens it will be accompanied by either a msg parameter or error_code and error_msg parameters together.

{
    "success": false,
    "error_code": 4,
    "error_msg": "You have reached your monthly free API usage limit. Please add a payment method in your account dashboard to continue using the API.",
    "execution_time": 0.13372898101807
}
{
    "success": false,
    "msg": "Missing required parameter 'email'"
}

Encoding Requests

 

The API expects all requests with parameters to be made as x-www-form-urlencoded. Submitting your request with any other encoding will result in missing parameters and a failed request.

/account

 
posthttps://api.neverbounce.com/v3/account
curl -X POST https://api.neverbounce.com/v3/account
    -d access_token={access_token}
A binary file was returned

You couldn't be authenticated

{
    "success":true,
    "credits":"35539",
    "jobs_completed":"84",
    "jobs_processing":"0",
    "execution_time":0.02251508712769
}

Form Data

access_token
string
required

The access token for this request

 

This endpoint does not return the free credits balance or monthly usage totals.

Property
Description

credits

Number of credits remaining in your account

jobs_completed

Number of jobs completed

jobs_processing

Number of jobs currently being processed

/single

 
posthttps://api.neverbounce.com/v3/single
curl -X POST https://api.neverbounce.com/v3/single
    -d access_token={access_token}
    -d email={email}
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "result": 0,
    "result_details": 0,
    "execution_time": 0.47218990325928
}

Form Data

access_token
string
required

The access token for this request

email
string
required

The email to verify

 

The results for single verifications are not stored in our system and are not available on​ the dashboard.

Result Codes

Within the response is a result property containing an integer that correlates to a result code listed int the table below. For more information about result codes visit our help docs.

Result Integer
Description

0

Valid

1

Invalid

2

Disposable

3

Catchall

4

Unknown

Result Details

The result_details property has been depreciated.

Result Detail Integer
Description

0

No additional details available

1

Bad Syntax

Point of Entry Usage

A common scenario for using the single endpoint is to verify emails at the point of entry; helping to keep your user base or newsletter list clean. At the point of entry, we suggest allowing valid, catchall, and unknown emails to proceed while blocking only disposable and invalid emails. It is important to allow unknown results to proceed as they may occur more frequently with the single endpoint than it does with bulk verification.

Additionally, we’ve found that with some smaller email hosts it is not uncommon to take several seconds (sometimes tens of seconds) to respond. It’s, for this reason, we suggest enforcing a client side timeout of approximately 10 seconds in your HTTP request library (ie: Curl, Guzzle, Httparty, etc…) and treat any timeouts as unknowns.

/bulk

 
posthttps://api.neverbounce.com/v3/bulk
curl -X POST https://api.neverbounce.com/v3/bulk
    -d access_token={access_token}
    -d input_location={input_location}
    -d input={input}
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "job_id": 194459,
  "job_status": 0,
  "job_file": "2017-04-26.api_job.1054.590102fbcae30.csv",
  "execution_time": 0.60870909690857
}

Form Data

access_token
string
required
input_location
int32
required

The source of the input data. 0 = Remote URL. 1 = Supplied Data.

input
string
required

Either a URL to the input or raw data as described by input_location

filename
string

The name that will be displayed in dashboard.

run_sample
string

Set this to 1 to start the job as a free list analysis.

 

The bulk endpoint provides high-speed validation on a list of email addresses. You can use the status endpoint to retrieve real-time statistics about a bulk job in progress. Once the job has finished, the results can be retrieved with our download endpoint. Read more about this workflow here.

When creating a new job, verification will begin automatically after it has been indexed.

Run Sample

The bulk endpoint has the ability to run a sample on the list and provide you with an estimated bounce rate without costing you. Based on the estimated bounce rate you can decide whether or not to perform the full validation or not. You can start validation by calling the start_job endpoint. Read more about running a sample here.

Input & Input Location

The bulk endpoint can receive input in multiple ways. The input_location parameter describes the contents of the input parameter. The input parameter may be a list of encoded email addresses, a file hosted at a remote URL, or other resource identifier based on the value of input_location. For now, two input_location styles are available. Remote URL and Supplied Data.

Remote URL

Using a remote URL allows you to host the file and provide us with a direct link to it. The file should be a list of emails separated by line breaks or a standard CSV file. We support most common file transfer protocols and their related authentication mechanisms. We suggest using either HTTP, HTTPS, FTP, FTPS or SFTP. When using a URL that requires authentication be sure to pass the username and password in the actual URL. When using SFTP keep in mind that we do not currently support key based authentication.

# Basic url
http://example.com/full/path/to/file

# HTTP Basic Auth
http://name:passwd@example.com/full/path/to/file

# FTP with authentication
ftp://name:passwd@example.com:21/full/path/to/file

Supplied Data

Supplying the data directly gives you the option to dynamically create email lists on the fly. input will accept a list of emails separated by line breaks or the data from a CSV file. When using this method be sure that you are properly encoding the data to ensure it has not become mangled.

Separating emails with \n (or other newline representations) is not the same as separating them with newline characters. When it comes time to encode the list of emails the \n representation will be encoded as the literal \ and n characters separately.

/status

 
posthttps://api.neverbounce.com/v3/status
curl -X POST https://api.neverbounce.com/v3/status
    -d access_token={access_token}
    -d job_id={job_id}
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "id": "194459",
  "status": "4",
  "type": "1",
  "input_location": "1",
  "orig_name": "2017-04-26.api_job.1054.590102fbcae30.csv",
  "stats": {
    "total": 1,
    "processed": 1,
    "valid": 1,
    "invalid": 0,
    "catchall": 0,
    "disposable": 0,
    "unknown": 0,
    "duplicates": 0,
    "bad_syntax": 0,
    "billable": 1,
    "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}",
  "execution_time": 0.015229940414429
}
{
  "success": true,
  "id": "194459",
  "status": "4",
  "type": "1",
  "input_location": "1",
  "orig_name": "2017-04-26.api_job.1054.590102fbcae30.csv",
  "stats": {
    "total": 1,
    "processed": 1,
    "valid": 1,
    "invalid": 0,
    "catchall": 0,
    "disposable": 0,
    "unknown": 0,
    "duplicates": 0,
    "bad_syntax": 0,
    "billable": 1,
    "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": [],
  "execution_time": 0.012382984161377
}

Form Data

access_token
string
required
job_id
int32
required

ID of the job to check the status for

version
string

Set this to 3.1 to retrieve the job_details

 

Statuses

Below are the various status codes that may populate the status property.

Status Integer
Description

-1

Job uploading, or transmission in progress.

0

Job has been received successfully and has entered the system queue.

1

Parsing your file to determine totals, detect bad data, and duplicate entries.

2

Job parsing has completed, this job is ready to run.

3

Job is currently in progress.

4

Job has successfully completed, results are available.

5

An unexpected failure has occurred, this job could not run (typically due to bad CSV data).

File Details

Contains information we've gathered from the file. It may be useful when trying to debug a job that failed.

This property is returned as a JSON string and will need to be inflated before accessing the properties.

Property
Description

email_col_i

Zero-based index of the column the emails are contained

tot_cols

Number of columns we found in the CSV

delimiter

The delimiter we detected from the CSV

has_header

Whether or not we detected a header

size

The size of the file or data supplied in bytes

tot_records

Total number of records detected in CSV

tot_emails

Total number fo emails found in the CSV

Job Details

Returned with version 3.1 or later

Property
Description

sample_status

Only available after free analysis
Contains integer describing the sample status. See Sample Statuses for additional details.

sample_details

Only available after free analysis
Contains details about the free sample after completion. See Sample Details for additional details.

Sample Status

Status Integer
Description

1

Indicates we have received the request to run the job as a sample.

2

We are currently processing your free sample job.

3

We have finished processing your sample job.

4

We have finished processing your sample job.

Sample Details

Property
Description

sample_size

The number of records chosen to test for a free sample (typically 10% of the total)

sample_stats

Contains the job's analysis results

bounce_estimate

The estimated bounce rate for this list (0.0 is 0% and 1.0 is 100%)

/start_job

 
posthttps://api.neverbounce.com/v3/start_job
curl -X POST https://api.neverbounce.com/v3/start_job
    -d access_token={access_token}
    -d job_id={job_id}
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "execution_time": 0.023593902587891
}

Form Data

access_token
string
required
job_id
string
required
 

This endpoint only needs to be called when you want to start a bulk job that was created with the run_sample parameter

/download

 
posthttps://api.neverbounce.com/v3/download
curl -X POST https://api.neverbounce.com/v3/download
    -d access_token={access_token}
    -d job_id={job_id}
A binary file was returned

You couldn't be authenticated

support@neverbounce.com,valid
invalid@neverbounce.com,invalid

Form Data

access_token
string
required
job_id
int32
required

Job ID to download the results of

valids
int32

Include valid records

invalids
int32

Include invalid records

catchall
int32

Include catchall records

disposable
int32

Include disposable records

unknowns
int32

Include unknown records

duplicates
int32

Include duplicate records

 

This endpoint does not respond in JSON unless an error has occurred​.

This endpoint will return all the job data in the original CSV format it was received as with the addition of a column containing the result.

If you only specify a job_id you will receive all results. However, if you specify additional parameters, any excluded parameters will be assumed to be false.

/delete_user_job

 
posthttps://api.neverbounce.com/v3/delete_user_job
curl -X POST https://api.neverbounce.com/v3/delete_use_job
    -d access_token={access_token}
    -d job_id={job_id}
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "job_id": 206814,
    "execution_time": 0.13731288909912
}

Form Data

access_token
string
required
job_id
string
required
 

A job cannot be deleted during indexing, processing or a sample run.

/list_user_jobs

 
posthttps://api.neverbounce.com/v3/list_user_jobs
curl -X POST https://api.neverbounce.com/v3/list_user_jobs
    -d access_token={access_token}
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "jobs": [
    {
      "id": "194459",
      "user_id": "1054",
      "purchased": "1",
      "status": "4",
      "type": "1",
      "input_location": "1",
      "orig_resource": "2017-04-26.api_job.1054.590102fbcae30.csv",
      "orig_name": "2017-04-26.api_job.1054.590102fbcae30.csv",
      "stats": {
        "total": 1,
        "processed": 1,
        "valid": 1,
        "invalid": 0,
        "catchall": 0,
        "disposable": 0,
        "unknown": 0,
        "duplicates": 0,
        "bad_syntax": 0,
        "percent_complete": 100,
        "billable": 1,
        "t": 1,
        "p": 1,
        "g": 1,
        "b": 0,
        "c": 0,
        "d": 0,
        "u": 0,
        "job_time": 0,
        "avg_recs_per_sec": 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",
      "result_db_details": "{\"version\":4,\"results_db_handle\":\"nb.db.us_east.vpc2.rescol7\"}",
      "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}",
      "callback_details": "{\"callback_url\":\"\",\"callback_params\":\"\"}",
      "job_details": "{\"internal_s3_handle\":\"default\",\"job_process\":null,\"indexing_progress\":1,\"dedup_progress\":1}",
      "active_runners": null
    }
  ]
}

Form Data

access_token
string
required
 

This will list all the jobs in your account included jobs uploaded using the dashboard.