Developers | NeverBounce

Getting Started

 

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

The standard 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. Instead please use our Javascript Widget.

Authentication

 

API keys are sensitive and give access to the data in your account as well as access to verify emails. Only trusted sources should be given access to these keys to protect your account. If you suspect a key has been compromised reset the key immediately from the corresponding app's dashboard page.

Version 4 of our API simplifies the authentication schema by using static API keys that look like this: secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. To get an API key log into your account and create a new Custom Integration App. After creation, you'll be taken to the overview page where you'll find you're newly created API key.

Custom Integration overview page

Custom Integration overview page

If for some reason you need to revoke or change the key, click "reset the API Key" in the the API key section.

You can authenticate your requests by including this API key as the key parameter in the request's query string. See the below samples for examples doing this.

The API username and secret key used to authenticate V3 API requests will not work to authenticate V4 API requests. If you are attempting to authenticate your request with the 8 character username or 12-16 character secret key the request will return an auth_failure error. The API key used for the V4 API will look like the following: secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. To create new V4 API credentials please go here.

# Key present in request URI
curl -X GET 'https://api.neverbounce.com/v4/account/info?key=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

# Key in body of application/x-www-form-urlencoded request
curl -X POST https://api.neverbounce.com/v4/account/info \
	-d key=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  
# Key in body of application/json request
curl -X POST -H "Content-Type: application/json"\
	https://api.neverbounce.com/v4/account/info \
	-d '{"key":"secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'
 
<?php

// Specify API key and wrapper handles
// query string constrcution
\NeverBounce\Auth::setApiKey('secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
 
// Initialize NeverBounce client with API key
const client = new NeverBounce({apiKey: 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'});
 
import neverbounce_sdk

# Create sdk client with API key
client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
 
// Instantiate wrapper with API key
client := neverbounce.New("secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
 
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
 
// Create new NeverBounceSdk instance using api key
var sdk = new NeverBounceSdk("secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");
 
// Instantiate NeverbounceClient
NeverbounceClient neverbounceClient = NeverbounceClientFactory.create("secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Error Handling

 

HTTP Errors (4xx/5xx)

As with any web service, our API will return 4xx and 5xx level errors when appropriate. Always check the status code to ensure the request was successfully received and successfully handled.

A 4xx level error code indicates that something is wrong with the request. Our recommendation is to double check the request for any typos.

A 5xx level error code indicates that something went wrong on our end. Our recommendation is to attempt the request again and check our API's status. If the request is still failing let us know at support@neverbounce.com.

API Errors

All 2xx level responses will contain a status property. This property will indicate whether the requested operation was successfully completed or if an error was encountered.

When an error does occur a message property will be included with a detailed message about why it failed. These error messages will be returned with a 200 level status code.

{
  "status":"general_failure",
  "message":"Missing required parameter 'key'",
  "execution_time":5
}
Status Code
Description

success

The request was successful

general_failure

Something went wrong with the request; check the message property for further details

auth_failure

The request couldn't be authenticated; ensure your API key has been typed correctly and that you're using a V4 API key (See authentication for more info)

temp_unavail

An internal error has occurred; typically this indicates a partial service interruption​

throttle_triggered

The request was rejected due to rate limiting; try again shortly

bad_referrer

The referrer for this request is not trusted

Language Specific Examples 

<?php

try {
    // Call wrapper method here
} catch (\NeverBounce\Errors\AuthException $e) {
    // The API credentials used are bad, have you reset them recently?
} catch (\NeverBounce\Errors\BadReferrerException $e) {
    // The script is being used from an unauthorized source, you may need to
    // adjust your app's settings to allow it to be used from here
} catch (\NeverBounce\Errors\ThrottleException $e) {
    // Too many requests in a short amount of time, try again shortly or adjust
    // your rate limit settings for this application in the dashboard
} catch (\NeverBounce\Errors\HttpClientException $e) {
    // An error occurred processing the request, something may be wrong with
    // the Curl PHP extension or your network
} catch (\NeverBounce\Errors\GeneralException $e) {
    // A non recoverable API error occurred check the message for details
} catch (Exception $e) {
    // An error occurred unrelated to the API
}
 
// The Node.JS wrapper does not throw exceptions. Instead it utilizes 
// asynchronous promises to handle successful and erroneous responses.
// 
// A rejected promise will contain the error object as the argument. The error
// object itself will contain both a `type` and `message`. See the example below.

client.account.info().then(
    resp => console.log(resp), // Successful response fulfilled
    err => { // Erroneous response rejected
        switch(err.type) {
            case 'AuthError':
                // The API credentials used are bad, have you reset them recently?
                break;
            case 'BadReferrerException':
                // The script is being used from an unauthorized source, you may need to
                // adjust your app's settings to allow it to be used from here
                break;
            case 'ThrottleError':
                // Too many requests in a short amount of time, try again shortly or adjust
                // your rate limit settings for this application in the dashboard
                break;
            case 'GeneralError':
                // A non recoverable API error occurred check the message for details
                break;
            default:
                // Other non specific errors
                break;
        }
    }
);
 
try:
    # Call wrapper method here
except neverbounce_sdk.AuthFailure as e:
    # The API credentials are bade, have you reset them recently?
except neverbounce_sdk.BadReferrer as e:
    # The script is being used from an unauthorized source, you may need to
    # adjust your app's settings to allow it to be used from here
except neverbounce_sdk.ThrottleTriggered as e:
    # Too many requests in a short amount of time, try again shortly or adjust
    # your rate limit settings for this application in the dashboard
except neverbounce_sdk.GeneralException as e:
    # A non recoverable API error occurred check the message for details
 
resp, err := // call client method
if err != nil {
	// Attempt to cast the error into a neverbounce.Error to
	// handle-able error objects
	if nbError, ok := err.(*neverbounce.Error); ok {
		// Check Error types
		if nbError.Type == neverbounce.ErrorTypeAuthFailure {
			// The API credentials used are bad, have you reset them recently?
		} else if (nbError.Type == neverbounce.ErrorTypeBadReferrer) {
			// The script is being used from an unauthorized source, you may need to
			// adjust your app's settings to allow it to be used from here
		} else if (nbError.Type == neverbounce.ErrorTypeThrottleTriggered) {
			// Too many requests in a short amount of time, try again shortly or adjust
			// your rate limit settings for this application in the dashboard
		} else {
			// A non recoverable API error occurred check the message for details
		}
	} else {
		// Handle non NeverBounce errors
	}
}
 
begin
  client = NeverBounce::API::Client.new(...)
  resp = # Call client method
rescue => e
  # Log the error with full backtrace.
end
 
try
{
  // Call SDK method (use await)
  // e.g: var resp = await sdk.Account.Info();
}
catch (AuthException e)
{
  // The API credentials used are bad, have you reset them recently?
}
catch (BadReferrerException e)
{
  // The script is being used from an unauthorized source, you may need to
  // adjust your app's settings to allow it to be used from here
}
catch (ThrottleException e)
{
  // Too many requests in a short amount of time, try again shortly or adjust
  // your rate limit settings for this application in the dashboard
}
catch (GeneralException e)
{
  // A non recoverable API error occurred check the message for details
}
catch (Exception e)
{
  // An error occurred unrelated to the API
}

Encoding Requests

 

Version 4 of the API allows the POST and GET HTTP verbs to be used interchangeably. Endpoints listed in this document have recommended HTTP verbs listed however these are not strictly enforced. The API does not support other HTTP verb methods (e.g. OPTION, HEAD, PUT, DELETE, etc..) at this time.

In addition to the HTTP verbs, the API also accepts both application/x-www-form-urlencoded and application/json content-types. Below you will see several examples of correct and incorrect usage.

# GET request with querystring in URI
curl -X GET 'https://api.neverbounce.com/v4/account/info?key=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

# GET request with application/json encoded body
curl -X GET -H "Content-Type: application/json"\
	https://api.neverbounce.com/v4/account/info \
	-d '{"key":"secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'

# POST request with querystring in URI
curl -X POST 'https://api.neverbounce.com/v4/account/info?key=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

# POST request with application/x-www-form-urlencoded encoded body
curl -X POST https://api.neverbounce.com/v4/account/info \
	-d key=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  
# POST request with application/json encoded body
curl -X POST -H "Content-Type: application/json"\
	https://api.neverbounce.com/v4/account/info \
	-d '{"key":"secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'
 
# POST request with mismatched Content-Type and data encoding
curl -X POST -H "Content-Type: application/json"\
	https://api.neverbounce.com/v4/account/info \
	-d key=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  
# POST request with application/json encoded body with no Content-Type specified
# (request libraries typically set x-www-form-urlencoded as default) 
curl -X POST https://api.neverbounce.com/v4/account/info \
	-d '{"key":"secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'

# PUT requests are not supported
curl -X PUT -H "Content-Type: application/json"\
	https://api.neverbounce.com/v4/account/info \
	-d key=secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Boolean Values

When working with our API you will encounter several parameters that accept boolean values. The acceptable representation of these values depends on requests encoding. With application/json we accept both boolean (true/false) and integer (1/0) representations. application/x-www-form-urlencoded on the other hand only accepts integer (1/0) representations.

Usage Guidelines

 

Our API is designed to accept both one-off verification requests as well as bulk verification requests. To ensure the most accurate results and efficiency of the verification, it's important to know when each option should be used and the respective limits of both.

Single Verification

  • Should be used in response to an action, like a form submission or button click
  • Do NOT use single verification for verifying emails in an existing list or database one-by-one. Your account may be locked and API access disabled if used for this purpose. Use the bulk verification for this purpose.

Bulk Verification

  • Should be used to verify databases or lists of several emails
  • You should submit all the data you have for verification in a single job rather than multiple jobs. It is better to submit a single list of 10k emails rather than 10 lists of 1k emails each. This allows the verification system to properly deduplicate the emails and allows a more efficient verification.
  • If you're collecting data from external sources like a CRM or ERP, you should buffer the data locally and submit it as a single job rather than submitting each chunk of data separately.
  • Do NOT create more than 10 jobs for every 100k items per hour. Sending too many small jobs in a short amount of time can result in your account being locked and API access disabled. Exceptions can be made for some use cases, please contact us with your scenario if you'd like this exception to be made.

Account

 

Account endpoints allow to programmatically check your account's balance and how many jobs are currently running on your account.

/info

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.neverbounce.com/v4/account/info
curl --request GET\
  --url 'https://api.neverbounce.com/v4/account/info?key={api_key}'
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

// Make request for API info
$info = \NeverBounce\Account::info();
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Get account info
client.account.info().then(
    resp => // Handle successful response
    err => // Handle error response
);
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Get account info
info = client.account_info();
// Instantiate wrapper
client := neverbounce.New("api_key")

// Get account info
accountInfo, err := client.Account.Info()
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Get account info
resp = client.account_info
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Get account info
AccountInfoResponseModel resp = sdk.Account.Info().Result;
// Instantiate Client
NeverbounceClient neverbounceClient = NeverbounceClientFactory.create(apiKey);

// Make Request
AccountInfoResponse accountInfoResponse = neverbounceClient.createAccountInfoRequest().execute();
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "status": "success",
    "credits_info": {
        "paid_credits_used": 0,
        "free_credits_used": 0,
        "paid_credits_remaining": 9950791,
        "free_credits_remaining": 0
    },
    "job_counts": {
        "completed": 409,
        "under_review": 0,
        "queued": 0,
        "processing": 0
    },
    "execution_time": 896
}
 

Single

 

Single verification allows you verify individual emails and gather additional information pertaining to the email.

Billing

Each verification performed over the Single endpoints cost 1 credit. This includes duplicate verifications requests and bad syntax data.

/check

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.neverbounce.com/v4/single/check
# Be sure to encode email before making the request (@ becomes %40)
curl --request GET\
  --url 'https://api.neverbounce.com/v4/single/check?key={api_key}&email={email}'
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

// Make verification request, specify optional $max_execution_time
$result = \NeverBounce\Single::check(
  'support@neverbounce.com', // Email to verify
  true, // Address info
  true, // Credits info
  10 // Timeout in seconds
);
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

/// Verify an email
client.single.check(
  'support@neverbounce.com', 
  true, // Address info
  true // Credits info
  10 // timeout
).then(
    result => // Handle success response
    err => // Handle error response
);
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Verify email
verification = client.single_check(
  email='support@neverbounce.com',
  address_info=True,
  credits_info=True,
  timeout=10  # Timeout in seconds
)
// Instantiate wrapper
client := neverbounce.New("api_key")

// Verify an email
singleResults, err := client.Single.Check(&nbModels.SingleCheckRequestModel{
  Email:       "support@neverbounce.com",
  AddressInfo: true,
  CreditInfo:  true,
  Timeout:     10,
})
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Get account info
resp = client.single_check(
  email: "support@neverbounce.com", 
  address_info: true, 
  credits_info: true, 
  timeout: 10)
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create request model
var model = new SingleRequestModel();
model.email = "support@neverbounce.com";
model.credits_info = true;
model.address_info = true;
model.timeout = 10; 

// Verify single email
SingleResponseModel resp = sdk.Single.Check(model).Result;
// Instantiate Client
NeverbounceClient neverbounceClient = NeverbounceClientFactory.create(apiKey);

// Perform verification
SingleCheckResponse singleCheckResponse = neverbounceClient
            .prepareSingleCheckRequest()
            .withEmail("support@neverbounce.com")
            .withAddressInfo(true)
            .withCreditsInfo(true)
            .withTimeout(10)
            .build()
            .execute()
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "status": "success",
  "result": "valid",
  "flags": [
    "has_dns",
    "has_dns_mx"
  ],
  "suggested_correction": "",
  "execution_time": 499
}
{
  "status": "success",
  "result": "valid",
  "flags": [
    "has_dns",
    "has_dns_mx",
    "role_account"
  ],
  "suggested_correction": "",
  "address_info": {
    "original_email": "support@neverbounce.com",
    "normalized_email": "support@neverbounce.com",
    "addr": "support",
    "alias": "",
    "host": "neverbounce.com",
    "fqdn": "neverbounce.com",
    "domain": "neverbounce",
    "subdomain": "",
    "tld": "com"
  },
  "execution_time": 399
}
{
    "status": "success",
    "result": "valid",
    "flags": [
        "smtp_connectable",
        "has_dns",
        "has_dns_mx"
    ],
    "suggested_correction": "",
    "credits_info": {
        "paid_credits_used": 1,
        "free_credits_used": 0,
        "paid_credits_remaining": 9950778,
        "free_credits_remaining": 0
    },
    "execution_time": 350
}

Query Params

email
string
required

The email to verify

address_info
boolean

Include additional address info in response (default: false)

credits_info
boolean

Include account credit info in response (default: false)

timeout
int32

The maximum time in seconds we should try to verify the address

 

The Timeout Parameter

The timeout parameter tells the API how long it should try to verify an email before giving up and returning an unknown result code. The total request time can exceed this timeout, as network latency is not taken into consideration. This can be helpful when verifying emails at the point of entry to prevent long wait times for your users.

Usage Guidelines

Please be sure to review our usage guidelines for the API here.

Handling Aliases

When verifying emails that contain aliases that use a + character extra consideration needs to be taken when encoding these for x-www-form-urlencoded content-types. Make sure this character is being encoded as %2B, as the + character is treated as a non-breaking space when the string is decoded.

Result Codes

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

Flags

The flags will give you additional information that we discovered about the domain during verification. Below is a list of common flags you may encounter.

Flag
Description

has_dns

The input has one or more DNS records associated with the hostname.

has_dns_mx

The input has mail exchanger DNS records configured.

bad_syntax

The input given doesn't appear to be an email.

free_email_host

This email is registered on a free-mail host. (e.g: yahoo.com, hotmail.com)

profanity

role_account

This email is a role-based email address (e.g: admin@, help@, sales@)

disposable_email

The input given is a disposable email.

government_host

The input given is a government email.

acedemic_host

The input given is a acedemic email.

military_host

The input given is a military email.

international_host

INT designated domain names.

squatter_host

Host likely intended to look like a big-time provider (type of spam trap).

spelling_mistake

The input was misspelled

bad_dns

temporary_dns_error

connect_fails

Unable to connect to remote host.

accepts_all

Remote host accepts mail at any address.

contains_alias

The email address supplied contains an address part and an alias part.

contains_subdomain

The host in the address contained a subdomain.

smtp_connectable

We were able to connect to the remote mail server.

spamtrap_network

Host is affiliated with a known spam trap network.

Suggested Correction

These are soft suggestions that may correct common typos such as "gmal.com" or "hotmal.com".

Webhooks

 

The single/check endpoint can be used as a webhook by adding the properties to the end of URI as a query string. This lets you easily add verification to your CRM and existing tools without any complex programming or development time.

To create a webhook follow this link. Once you've created the webhook you'll be giving a URL that looks something like the one below:

https://api.neverbounce.com/v4/single/check?key=webhook_secret_abcdefghijklmnopqrstuvwxyz&email={email}
 
https://api.neverbounce.com/v4/single/check?key=webhook_secret_abcdefghijklmnopqrstuvwxyz&email={email}&address_info=1
 
https://api.neverbounce.com/v4/single/check?key=webhook_secret_abcdefghijklmnopqrstuvwxyz&email={email}&credits_info=1

In order to use this webhook simply replace the {email} placeholder with the email you want to verify. Because this is the same endpoint as described in the previous section you can still use the address_info and credits_info parameters here as well.

Webhooks are not safe to use in client-side scripts (e.g. jQuery, Javascript). The URL contains a sensitive API key that should be treated just like a regular API key.

Jobs

 

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.

Billing

You will only be charged for the billable amount of emails found in your list. The billable amount of emails is the number of unique syntactically valid emails.

Credits will be charged from your account when a full verification is​​ started. Starting a job as with the run_sample parameter does not cost any credits.

/search

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.neverbounce.com/v4/jobs/search
curl --request GET\
  --url 'https://api.neverbounce.com/v4/jobs/search?key={api_key}'
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

$query = [
//    'job_id' => 10000, // Filter jobs based on id
//    'filename' => 'Book1.csv', // Filter jobs based on filename
//    'job_status' => 'complete', // Show completed jobs only
//    'page' => 1, // Page to start from
//    'items_per_page' => 10, // Number of items per page
];

// Search for jobs in your account
$job = \NeverBounce\Jobs::search($query);
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Search jobs
client.jobs.search({
//    'job_id': 10000, // Filter jobs based on id
//    'filename': 'Book1.csv', // Filter jobs based on filename
//    'job_status': 'complete', // Show completed jobs only
//    'page': 1, // Page to start from
//    'items_per_page': 10, // Number of items per page
}).then(
    resp => // Handle successful response,
    err => // Handle error response
););
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key)

# Get jobs
jobs = client.jobs_search(
    # job_id=10000,  # Filter jobs based on id
    # filename='Book1.csv',  # Filter jobs based on filename
    # job_status='complete',  # Show completed jobs only
    # page=1,  # Page to start from
    # items_per_page=10,  # Number of items per page
)

# iterate through jobs
for job in jobs:
    print(job)
// Instantiate wrapper
client := neverbounce.New("api_key")

// Search for jobs
searchResults, err := client.Jobs.Search(&nbModels.JobsSearchRequestModel{
  //JobFilename: "MyListName.csv",
  //JobID: 289010,
  //JobStatus: "complete",
  //ItemsPerPage: 10,
  //Page: 1,
})
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Search for jobs
resp = client.jobs_search(page: 1, per_page: 10)

# Process items:
resp.results.each do |item|
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create search model
var model = new JobSearchRequestModel();
//model.job_id = 288025;
//model.job_status = "complete";
//model.filename = "MyFile.csv";
//model.items_per_page = 10;
//model.page = 1;

// Get jobs
JobSearchResponseModel resp = sdk.Jobs.Search(model).Result;
// Instantiate Client
NeverbounceClient neverbounceClient = NeverbounceClientFactory.create(apiKey);

// Search for jobs
JobsSearchResponse jobsSearchResponse = neverbounceClient
        .prepareJobsSearchRequest()
        .withJobId(jobId)
        .build()
        .execute();
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "status": "success",
  "total_results": 1,
  "total_pages": 1,
  "query": {
    "page": 1,
    "items_per_page": 10,
  },
  "results": [
    {
      "id": 277461,
      "status": "complete",
      "filename": "Created from Array.csv",
      "created_at": "2017-07-25 16:25:19",
      "started_at": "2017-07-25 16:25:30",
      "finished_at": "2017-07-25 16:25:31",
      "total": {
        "records": 2,
        "billable": 2,
        "processed": 2,
        "valid": 0,
        "invalid": 2,
        "catchall": 0,
        "disposable": 0,
        "unknown": 0,
        "duplicates": 0,
        "bad_syntax": 0
      },
      "bounce_estimate": 0,
      "percent_complete": 100
    }
  ],
  "execution_time": 388
}

Query Params

job_id
int32

Filter jobs based on it's id

filename
string

Filter jobs based on the filename (exact match)

job_status
string

Filter jobs by the job status

page
int32

The page to grab the jobs from

items_per_page
int32

The number of jobs to display

 

/create

 

Query Auth

 Authentication is required for this endpoint.
posthttps://api.neverbounce.com/v4/jobs/create
# x-www-form-urlencoded request w/ remote_url input
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=true\
  --data auto_start=true\
  --data input='https://mydomain.com/my_file.csv'
# x-www-form-urlencoded request w/ supplied data
curl --request POST\
  --url https://api.neverbounce.com/v4/jobs/create\
  --data key={api_key}\
  --data input_location='supplied'\
  --data filename='SampleNeverBounceAPI.csv'\
  --data auto_parse=true\
  --data auto_start=true\
  --data 'input[0][0]=support%40neverbounce.com'\
  --data 'input[0][1]=Fred%20McValid'\
  --data 'input[1][0]=invalid%40neverbounce.com'\
  --data 'input[1][1]=Bob%20McInvalid'
  
# JSON encoded request w/ supplied data
curl --request POST\
  --header "Content-Type: application/json"\
  --url https://api.neverbounce.com/v4/jobs/create\
  --data '{
    "key": {api_key},
    "input_location": "supplied",
    "filename": "SampleNeverBounceAPI.csv",
    "auto_start": true,
    "auto_parse": true,
    "input": [
        [
            "support@neverbounce.com",
            "Fred McValid"
        ],
        [
            "invalid@neverbounce.com",
            "Bob McInvalid"
        ]
    ]
}'
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

// Build json
$arr = [
    [
        'support@neverbounce.com',
        'Fred McValid'
    ],
    [
        'invalid@neverbounce.com',
        'Bob McInvalid'
    ]
];

// Make a new job with the supplied data
$job = \NeverBounce\Jobs::create(
  $arr, // input
  \NeverBounce\Jobs::SUPPLIED_INPUT, // Either `supplied` or `remote_url`
  'SampleNeverBounceAPI.csv', // Friendly name that can be used to identify job
  false, // Run as sample
  true, // Auto parse
  true, // Auto start
);

// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Verify a list of emails
client.jobs.create(
    [
        {
            'id': '12345',
            'email': 'support@neverbounce.com',
            'name': 'Fred McValid'
        },
        {
            'id': '12346',
            'email': 'invalid@neverbounce.com',
            'name': 'Bob McInvalid'
        }
    ],
    'supplied', // Either `supplied` or `remote_url`
    'Created from Array.csv', // Friendly name that can be used to identify job
  	false, // Run sample
  	true, // Auto parse
    true // Auto run
).then(
    resp => // Handle success response
    err => // Handle error response
);
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Create array of data
inputData = [
  {
    'id': '12345',
    'email': 'support@neverbounce.com',
    'name': 'Fred McValid'
  },
  {
    'id': '12346',
    'email': 'invalid@neverbounce.com',
    'name': 'Bob McInvalid'
  }
]

# Create Job
resp = client.jobs_create(
  input=inputData,
  filename="Created from Python Wrapper.csv",
  # auto_parse=True,
  # auto_start=True,
  # as_sample=False,
  # from_url=False
)
// Instantiate wrapper
client := neverbounce.New("api_key")

// Build data map
createData := map[int]interface{}{}
createData[0] = map[string]interface{}{
  "id":    12345,
  "email": "support@neverbounce.com",
  "name":  "Bob McValid",
}
createData[1] = map[string]interface{}{
  "id":    12346,
  "email": "invalid@neverbounce.com",
  "name":  "Fred McInvalid",
}

// Create a job from supplied data
jobInfo, err := client.Jobs.CreateFromSuppliedData(&nbModels.JobsCreateSuppliedDataRequestModel{
  SuppliedData: createData,
  AutoParse:    false,
  AutoRun:      false,
  RunSample:    false,
  FileName:     "Created from Golang.csv",
})
if err != nil {
  panic(err)
}

// Create a job from a remote URL
jobInfo, err := client.Jobs.CreateFromRemoteURL(&nbModels.JobsCreateRemoteURLRequestModel{
  RemoteURL: "https://example.com/file.csv",
  AutoParse: true,
  AutoRun:   false,
  RunSample: false,
  FileName:  "Created from Golang.csv",
})
if err != nil {
  panic(err)
}
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Create job with supplied input
resp = client.jobs_create(supplied_input: [["alice@isp.com", "Alice Roberts"], ["bob.smith@gmail.com", "Bob Smith"]])

# Create job with remote file
resp = client.jobs_create(remote_input: "http://example.com/emails.csv", filename: "emails.csv", run_sample: true)
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

/**
 * Create a job using supplied data
 */

// Create supplied data model
var model = new JobCreateSuppliedDataRequestModel();
model.filename = "Created From dotNET.csv";
model.auto_parse = true;
model.auto_start = false;
model.input = new List<object>();
model.input.Add(new {id = "3", email = "support@neverbounce.com", name = "Fred McValid"});
model.input.Add(new {id = "4", email = "invalid@neverbounce.com", name = "Bob McInvalid"});

// Create job from supplied data
JobCreateResponseModel resp = sdk.Jobs.CreateFromSuppliedData(model).Result;

/**
 * Create a job using a remote url
 */

// Create remote url model
var model2 = new JobCreateRemoteUrlRequestModel();
model.filename = "Created From dotNET.csv";
model.auto_parse = true;
model.auto_start = false;
model.input = "https://example.com/file.csv";

// Create job from remote url
JobCreateResponseModel resp2 = sdk.Jobs.CreateFromRemoteUrl(model).Result;
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "status": "success",
  "job_id": 150970,
  "execution_time": 712
}

Body Params

input_location
string
required

The type of input being supplied. Accepted values are "remote_url" and "supplied".

input
json
required

The input to be verified

auto_parse
boolean

Should we begin parsing the job immediately? (default: false)

auto_start
boolean

Should we run the job immediately after being parsed? (default: false)

run_sample
boolean

Should this job be run as a sample? (default: false)

filename
string

This will be what's displayed in the dashboard when viewing this job

 

Usage Guidelines

Please be sure to review our usage guidelines for the bulk API here.

The jobs create endpoint allows you create verify multiple emails together, the same way you would verify lists in the dashboard. This endpoint will create a job and process the emails in the list (if auto_start is enabled) asynchronously. Verification results are not returned in the response. Read more about how to verify lists of emails here.

Auto Parse

This will enable or disable the indexing process from automatically starting as soon as you create a job. If set to 0 or false you will need to call the /parse endpoint after the job has been created to begin indexing. Defaults to 0

Auto Start

This will enable or disable the job from automatically beginning the verification process once it has been parsed. If this is set to 0 or false you will need to call the /start endpoint to begin verification. Setting this to 1 or true will start the job and deduct the credits. Defaults to 0

Run Sample

This 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 endpoint. Read more about running a sample here. Defaults to 0

Input & Input Location

This endpoint can receive input in multiple ways. The input_location parameter describes the contents of the input parameter. The input parameter may be an array of objects containing emails or a file hosted at a remote URI.

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 authentication mechanisms. When using a URL that requires authentication be sure to pass the username and password in the URI string.

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

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

# FTP with authentication
ftp://name:passwd@example.com:21/full/path/to/file.csv
 
id,email,name
"12345","support@neverbounce.com","Fred McValid"
"12346","invalid@neverbounce.com","Bob McInvalid"

Supplied Data

Supplying the data directly gives you the option to dynamically create email lists on the fly rather than having to write to a file. input will accept an array of objects or arrays that contain the email, as well as any ancillary data you wish to associate with the email (e.g. user IDs, names, contact information).

If the data is supplied as an object, the key names will be used for the column headers. If the data is supplied as an array, column headers will be ommitted. Below is a sample of what each looks like in JSON.

[
    {
        "id": 12345,
        "email": "support@neverbounce.com",
        "name": "Fred McValid"
    },
    {
        "id": 12346,
        "email": "invalid@neverbounce.com",
        "name": "Bob McInvalid"
    }
]
 
[
    [
        12345,
        "support@neverbounce.com",
        "Fred McValid"
    ],
    [
        12346,
        "invalid@neverbounce.com",
        "Bob McInvalid"
    ]
]

/parse

 

Query Auth

 Authentication is required for this endpoint.
posthttps://api.neverbounce.com/v4/jobs/parse
curl --request POST\
  --url https://api.neverbounce.com/v4/jobs/parse\
  --data key={api_key}\
  --data job_id={job_id}
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

// Make a new job with the supplied data
$job = \NeverBounce\Jobs::parse(
  $job_id,
  //false // Auto start
);
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Parse a job
client.jobs.parse(
  jobId,
  //false // Auto start
).then(
    resp => // Handle success response
    err => // Handle error response
);
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Parse job
resp = client.jobs_parse(
  job_id=289022,
  #auto_start=False
)
// Instantiate wrapper
client := neverbounce.New("api_key")

// Parse a job
parseInfo, err := client.Jobs.Parse(&nbModels.JobsParseRequestModel{
  JobID: 296050,
//  AutoStart: false,
})
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Parse job
resp = client.jobs_parse(job_id: 123)
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create parse job model
var model = new JobParseRequestModel();
model.job_id = 290561;
//model.auto_start = false;

// Parse job
JobParseResponseModel resp sdk.Jobs.Parse(model).Result;
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "status": "success",
  "queue_id": "NB-PQ-59246392E9E5D",
  "execution_time": 712
}

Body Params

job_id
int32
required

The id of the job to parse

auto_start
boolean

Should the job start processing immediately after it's parsed? (default: false)

 

This endpoint allows you to parse a job created with auto_parse disabled. You cannot reparse a list once it's been parsed.

/start

 

Query Auth

 Authentication is required for this endpoint.
posthttps://api.neverbounce.com/v4/jobs/start
curl --request POST\
  --url https://api.neverbounce.com/v4/jobs/start\
  --data key={api_key}\
  --data job_id={job_id}
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

// Start a job that has been parsed
$job = \NeverBounce\Jobs::start($job_id);
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Start a job
client.jobs.start(jobId).then(
    resp => // Handle successful response
    err => // Handle error response
);
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Start job
resp = client.jobs_start(job_id=289022)
// Instantiate wrapper
client = neverbounce.New("api_key")

// Start a job
startInfo, err := client.Jobs.Start(&nbModels.JobsStartRequestModel{
  JobID: 296050,
//  RunSample: false,
})
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Start a job
resp = client.client.jobs_start(job_id: 123)
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create start job model
var model = new JobStartRequestModel();
model.job_id = 290561;
//model.run_sample = true;

// Start job
JobStartResponseModel resp = sdk.Jobs.Start(model).Result;
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "status": "success",
  "queue_id": "NB-PQ-59246392E9E5D",
  "execution_time": 712
}

Body Params

job_id
int32
required

The id of the job to start

run_sample
boolean

Should this job be run as a sample? (default: false)

 

This endpoint allows you to start a job created or parsed with auto_start disabled. Once the list has been started the credits will be deducted and the process cannot be stopped or restarted.

/status

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.neverbounce.com/v4/jobs/status
curl --request GET\
  --url 'https://api.neverbounce.com/v4/jobs/status?key={api_key}&job_id={job_id}'
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

// Get the details about the job
$job = \NeverBounce\Jobs::status($job_id);
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Get the job status
client.jobs.status(jobId).then(
    resp => // Handle successful response,
    err => // Handle error response
);
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Get job status
resp = client.jobs_status(job_id=289022)
// Instantiate wrapper
client := neverbounce.New("api_key")

// Query a job's status
statusInfo, err := client.Jobs.Status(&nbModels.JobsStatusRequestModel{
  JobID: 296050,
})
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Parse job
resp = client.jobs_status(job_id: 123)
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create job status model
var model = new JobStatusRequestModel();
model.job_id = 290561;

// Query job status
JobStatusResponseModel resp = sdk.Jobs.Status(model).Result;
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "status": "success",
  "id": 277461,
  "filename": "Created from Array.csv",
  "created_at": "2017-07-25 14:52:27",
  "started_at": "2017-07-25 14:52:40",
  "finished_at": "2017-07-25 14:53:06",
  "total": {
    "records": 2,
    "billable": 2,
    "processed": 2,
    "valid": 0,
    "invalid": 2,
    "catchall": 0,
    "disposable": 0,
    "unknown": 0,
    "duplicates": 0,
    "bad_syntax": 0
  },
  "bounce_estimate": 0,
  "percent_complete": 100,
  "job_status": "complete",
  "execution_time": 322
}

Query Params

job_id
int32
required

The id of the job to check

 

Job Status

Job status will indicate what stage the job is currently in. This will be the primary property you'll want to check to determine what can be done with the job.

Status
Description

under_review

The job has fallen into our Q/A review and requires action on our end. Read more...

queued

The job has been queued, this is because we're either too busy or you have too many active jobs.

failed

The job failed, typically this is due to poorly formatted data.

complete

The job has completed verification and the results are ready for download.

running

The job is currently either running a sample or full verification.

parsing

The job has been received and we are parsing the data for emails and duplicate records.

waiting

The job has not yet run and is waiting to be started.

waiting_analyzed

The job has completed analysis and is waiting for further action.

uploading

The job is currently being uploaded to the system.

Totals

There are several items in the total object that give you an overview of verification results. These numbers are updated periodically during the verification process. Most of these properties correspond directly with the verification result codes; the other properties are explained below.

Property
Description

records

The number of rows we found in your file. This may include whitespace, empty rows, and other rows that don't contain syntactically correct emails.

billable

The number of rows we found syntactically correct emails in. This is number of credits processing this job will consume.

processed

The total number of emails that have been processed so far.

duplicates

The number of rows that contain duplicated emails. This is not the number of unique duplicates but the total of every instance.

bad_syntax

The number of records that do not contain data that looks like an email. This may include whitespace and empty rows as well as bad data.

Bounce Estimate

This property indicates the bounce rate we estimate the list to bounce at if sent to in its entirety. The value of this property will be a float between 0.0 and 100.0.

Percent Complete

This property indicates the overall progress of this job's verification. The value of this property will be a float between 0.0 and 100.0.

/results

 

Query Auth

 Authentication is required for this endpoint.
gethttps://api.neverbounce.com/v4/jobs/results
curl --request GET\
  --url 'https://api.neverbounce.com/v4/jobs/results?key={api_key}&job_id={job_id}'
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

$query = [
  //'items_per_page' => 10,
  //'page' => 1,
];

// Get the results from the job
$job = \NeverBounce\Jobs::results($job_id, $query);
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Get the job results
client.jobs.results(jobId, {
//    'page': 1, // Page to start from
//    'items_per_page': 10, // Number of items per page
}).then(
    resp => // Handle successful response,
    err => // Handle error response
);
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Get job's results
jobs = client.jobs_results(
    job_id=289022
    # page=1,  # Page to start from
    # items_per_page=10,  # Number of items per page
)

# Iterate through jobs
for job in jobs:
    print(job)
// Instantiate wrapper
client := neverbounce.New("api_key")

// Get the results for a job
resultsInfo, err := client.Jobs.Results(&nbModels.JobsResultsRequestModel{
  JobID: 296050,
  //ItemsPerPage: 10,
  //Page: 1,
})
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Download job results
resp = client.jobs_results(job_id: 123, page: 1, per_page: 20)

# Process items:
resp.results.items.each do |item| ...
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create job results model
var model = new JobResultsRequestModel();
model.job_id = 290561;
//model.items_per_page = 10;
//model.page = 1;

// Get job's results
JobResultsResponseModel resp = sdk.Jobs.Results(model).Result;
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "status": "success",
  "total_results": 3,
  "total_pages": 1,
  "query": {
    "job_id": 251319,
    "valids": 1,
    "invalids": 1,
    "disposables": 1,
    "catchalls": 1,
    "unknowns": 1,
    "page": 0,
    "items_per_page": 10
  },
  "results": [
    {
      "data": {
        "email": "email",
        "id": "id",
        "name": "name"
      },
      "verification": {
        "result": "invalid",
        "flags": [],
        "suggested_correction": "",
        "address_info": {
          "original_email": "email",
          "normalized_email": "",
          "addr": "",
          "alias": "",
          "host": "",
          "fqdn": "",
          "domain": "",
          "subdomain": "",
          "tld": ""
        }
      }
    },
    {
      "data": {
        "email": "support@neverbounce.com",
        "id": "12345",
        "name": "Fred McValid"
      },
      "verification": {
        "result": "valid",
        "flags": [
          "smtp_connectable",
          "has_dns",
          "has_dns_mx",
          "role_account"
        ],
        "suggested_correction": "",
        "address_info": {
          "original_email": "support@neverbounce.com",
          "normalized_email": "support@neverbounce.com",
          "addr": "support",
          "alias": "",
          "host": "neverbounce.com",
          "fqdn": "neverbounce.com",
          "domain": "neverbounce",
          "subdomain": "",
          "tld": "com"
        }
      }
    },
    {
      "data": {
        "email": "invalid@neverbounce.com",
        "id": "12346",
        "name": "Bob McInvalid"
      },
      "verification": {
        "result": "invalid",
        "flags": [
          "smtp_connectable",
          "has_dns",
          "has_dns_mx"
        ],
        "suggested_correction": "",
        "address_info": {
          "original_email": "invalid@neverbounce.com",
          "normalized_email": "invalid@neverbounce.com",
          "addr": "invalid",
          "alias": "",
          "host": "neverbounce.com",
          "fqdn": "neverbounce.com",
          "domain": "neverbounce",
          "subdomain": "",
          "tld": "com"
        }
      }
    }
  ],
  "execution_time": 55
}

Query Params

job_id
int32
required

The id of the job to retrieve results for

page
int32

The page to return the results from

items_per_page
int32

The number of results to be returned, between 1 and 1000

 

Data

The data object will contain the original data submitted for this row. If the source data was submitted via the API the data will have the same keys as when it was originally submitted. If submitted as a CSV in the dashboard the data will use the header row to determine the keys for the data when available.

Verification

The verification object contains the verification results for the email being verified. This object contains the same information that the single/check endpoint returns.

/download

 

This endpoint returns an application/octet-stream containing the job data as a CSV file. Because of this, the API explorer is not available.

There are several options that allow you download additional information about each string as well as several segmentation options available. The only required parameters for this endpoint are the API key and id of the job to download results from. Below is an example of a basic request that will return all five result codes.

curl -X GET\
  --url 'https://api.neverbounce.com/v4/jobs/download?key={api_key}&job_id={job_id}'

# The same request with explicitly defined parameters
curl -X GET\
  --url 'https://api.neverbounce.com/v4/jobs/download?key={api_key}&job_id={job_id}&valids=1&invalids=1&catchalls=1&unknowns=1&disposables=1&include_duplicates=0&email_status=1'
 
# The same request as POST with explicitly defined parameters
curl -X POST\
  --url 'https://api.neverbounce.com/v4/jobs/download'\
  --data key={api_key}\
  --data job_id={job_id}

# The same request as POST with explicitly defined parameters
curl -X POST\
  --url 'https://api.neverbounce.com/v4/jobs/download'\
  --data key={api_key}\
  --data job_id={job_id}\
  --data valids=1\
  --data invalids=1\
  --data catchalls=1\
  --data unknowns=1\
  --data disposables=1\
  --data include_duplicates=0\
  --data email_status=1
 
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

$query = [
];

// Download the job data as a CSV
$job = \NeverBounce\Jobs::download($job_id, $query);
 
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Create download query
const query = {};

// Download the results as a CSV
client.jobs.download(jobId, query).then(
    resp => // Handle successful response,
    err => // Handle error response
);
 
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Open file to write to
f = open('results.csv', mode='wb')

# Jobs download
resp = client.jobs_download(job_id=289022, fd=f)
f.close()
 
// Instantiate wrapper
client := neverbounce.New("api_key")

// Download the jobs results as a CSV and save to file
err := client.Jobs.Download(&nbModels.JobsDownloadRequestModel{
  JobID:            296050,
  // ...See JobsDownloadRequestModel for additional options
}, "test.csv")
 
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Download job as CSV
resp = client.jobs_download(job_id: 123)

# Parse CSV data
emails = CSV.parse(resp.raw)
 
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create job download model
var model = new JobDownloadRequestModel();
model.job_id = 290561;
// See model for additional options

// Download jobs' data
String resp = sdk.Jobs.Download(model).Result;
 
id,email,name,email_status
"12345","support@neverbounce.com","Fred McValid",valid
"12346","invalid@neverbounce.com","Bob McInvalid",invalid

Parameters

Segmentation

Parameter
Description

valids

Includes or excludes valid emails

invalids

Includes or excludes invalid emails

catchalls

Includes or excludes catchall (accept all / unverifiable) emails

unknowns

Includes or excludes unknown emails

disposables

Includes or excludes disposable emails

include_duplicates

If true then all instances of duplicated items will appear.

only_duplicates

If set this property overrides other segmentation options and the download will only return the duplicated items.

only_bad_syntax

If set this property overrides other segmentation options and the download will only return bad syntax records.

Appends

Parameter
Description

bad_syntax

Appends a yes/no column indicating if the record is bad syntax

free_email_host

Appends a yes/no column indicating if the email is a freemail address (e.g. gmail.com, hotmail.com, yahoo.com)

role_account

Appends a yes/no column indicating if the email is a role account (e.g. support@, info@, sales@)

addr

Appends a column indicating the address portion of the email. Generally, ​this is anything before the @ sign. If this address includes an email alias, the alias will not be returned as part of this field.

alias

Appends a column showing the alias portion of an email address. If an address contains an alias such as "david+test1@site.com" the alias portion is returned, otherwi​se this column is empty.

host

Appends a column showing the host portion of the email address. Generally this is everything after the @ sign.

subdomain

Appends a column to show the email host's subdomain if applicable. For example, if the host was site.example.com, the subdomain would show a response of "site".

domain

Appends a column to show the email host's domain name. This does not include any subdomain, if applicable, and does not include the TLD or top level domain portion. If the host was site.example.com, the domain would be "example".

tld

Appends a column to show the TLD or top level domain of the email host. If the host was "site.example.com", the TLD is "com".

fqdn

Appends a column to show the FQDN or "Fully Qualified Domain Name". This is the portion of the host that you use to query DNS information. In most cases, this will be the same as the host; however, if a subdomain was included this will be removed from the FQDN. For example, if the host was "zone-1.zone-2.site.example.com", the FQDN would be "example.com".

network

Appends a column to show the FQDN (Fully Qualified Domain Name) of the primary MX record. This is an attempt to determine the ISP hosting the email at a particular address and is useful for grouping addresses together by provider.

has_dns_info

Appends a column to show whether one or more DNS records exists for this host.

has_mail_server

Appends a column to show whether this host has one or more MX records defined in its DNS records.

mail_server_reachable

Appends a column to show whether NeverBounce was able to connect to a remote mail server identified by the host's MX records.

email_status_int

Appends the verification result code as an integer (0, 1, 2, 3, 4).

email_status

Appends the verification result code as a string (valid, invalid, disposable, catchall, unknown).

Settings

Parameter
Description

binary_operators_type

Determines how Yes/No columns are represented. Available settings are:

BIN_1_0 = 1/0 (default)
BIN_Y_N = Y/N
BIN_y_n = y/n
BIN_yes_no = yes/no
BIN_Yes_No = Yes/No
BIN_true_false = true/false

line_feed_type

Determines the type of linefeed character used to represent line breaks in the CSV. Available settings are:

LINEFEED_0A0D = \n\r (default)
LINEFEED_0D0A = \r\n
LINEFEED_0A = \n
LINEFEED_0D = \r

/delete

 

Query Auth

 Authentication is required for this endpoint.
posthttps://api.neverbounce.com/v4/jobs/delete
curl --request POST\
  --url https://api.neverbounce.com/v4/jobs/delete\
  --data key={api_key}\
  --data job_id={job_id}
<?php

// Set API key
\NeverBounce\Auth::setApiKey($api_key);

// Delete a job
$job = \NeverBounce\Jobs::delete($job_id);
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Delete the job
client.jobs.delete(jobId).then(
    resp => // Handle successful response,
    err => // Handle errors
);
import neverbounce_sdk

# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Delete job
resp = client.jobs_delete(job_id=289022)

// Instantiate wrapper
client := neverbounce.New("api_key")

// Delete a job
deleteInfo, err := client.Jobs.Delete(&nbModels.JobsDeleteRequestModel{
  JobID: 296050,
})
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Delete job
resp = client.jobs_delete(job_id: 123)
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create job delete model
var model = new JobDeleteRequestModel();
model.job_id = 290561;

// Delete job
JobDeleteRequestModel resp = sdk.Jobs.Delete(model).Result;
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "status": "success",
  "execution_time": 57
}

Body Params

job_id
int32
required

The id of the job to delete

 

Deleting a job is permanent!

The job and its results cannot be recovered once the job has been deleted. If the results are needed after a job has been deleted you will need to resubmit and reverify the data.

Overview

 

Installation

For installation instructions visit the widget's installation instructions here.

By default, the widget offers a quick and easy way to add our verification to your forms with minimal coding knowledge. However, in some cases, you may need additional functionality or need a more advanced integration with your existing application. This will likely be the case for many single page applications or web pages that load forms dynamically.

Below you will find the complete reference for the public methods, objects, and events the widget makes use of.

Authentication

It should be noted that the authentication mechanism used for the widget differs from the standard API. The widget will only work with keys that start with public_; all other keys will result in authentication failures. Likewise, keys starting with public_ cannot be used for the standard API.

Objects

 

There are several objects that you'll come across when working with the widget programmatically. This includes the widget's public API which is accessible in the browser as the _nb object.

API

 

This object is what handles the requests to the NeverBounce API. It can be accessed in the browser at window._nb.api.

getValidatePublic(email, successCallback, errorCallback)

This method performs a verification request directly. It accepts a single email as well as two callbacks. The first callback is called on a successful request and contains a Result Object as the first argument. The second callback is called when an error is encountered and will contain the error message as a string.

_nb.api.getValidatePublic('support@neverbounce.com',
    function(result) {
        // Returns a Result object
        console.log(result)
    },
    function(err) {
        // Returns error message as string
        console.log(err)
    }
)

sendEvent(event)

This method can be used to report back to the API what the status of the form is. These events are used to create the reports available on the widget's overview page.

The only events currently supported are form.load and form.completion. Abandoned forms are calculated from the difference between form.load and form.completion events.

// Send form load event
_nb.api.sendEvent('form.load');

// Send form completion event
_nb.api.sendEvent('form.completion');

FieldListener

 

Every time a field is registered with the widget a new FieldListener object is created. This object is what sets up the DOM for the field as well as holding the field's state. It contains several properties and methods that can be used for very low-level access to the field.

_error

This property will be set to false when no errors are present or it will be set to a string containing a relevant​ error message.

_lastValue

This property is used to prevent reverifying an email that has just been verified. Every time an API request is made the value that's being verified is set in this property. The next time the field is changed we'll verify the contents of the field is different than the value of this property.

_request

When an API request is currently being transmitted the request object will live here. To cancel an active request this property can be called as a function.

// Cancel an active request if it exists
if (obj._request) 
  obj._request();

_response

Initially, this property will be set to false. After a request to the API is attempted it will contain a Result object.

_timeout

This property contains the timeout used to defer the API requests until the user has stopped typing. If a timeout isn't currently active the property will be set to false.

The deferment time is set by the inputLatency option during setup.

id

The id is a universally unique identifier generated for this particular field. It can be used to find the DOM node for the field or the form containing the field.

// Get the field
let field = document.querySelector('[data-nb-id="' + event.detail.id + '"]');

// Get the form
var form = document.querySelector('form[data-nb-form="' + id + '"]');

forceUpdate()

This method allows you to programmatically invoke the onChange handler attached to the field. This will skip any inputLatency checks that the onChange handler typically performs. Below is an excerpt containing the private method that forceUpdate invokes.

/**
 * Handles the actual event actions
 * Typically called after doing some input filtering from the onChange 
 * event emitted by the field, but can also be called by forceUpdate()
 *
 * @param app The instance of FieldListener for the field
 * @param ele The DOM node for the field were working with
 */
function onChangeHandler(app, ele) {
    const value = ele.value;

    // Perform soft regex test before attempting api call
    const rgx = /[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?/;

    if (rgx.test(value)) {

        // If this is the same email as the last request, lets skip the check
        if (app._response( === false || app._lastValue !== value) {

            ele.dispatchEvent(nbEvent('loading', app));
            app._lastValue = value;
            app._request = api.getValidatePublic(value,
                function (result) {
                    app._response = result;
                    app._error = false;
                    ele.dispatchEvent(nbEvent('result', app));
                }.bind(app),
                function (err) {
                    app._response = new Result({result: 'error'});
                    app._error = err;
                    ele.dispatchEvent(nbEvent'clear', app));
                }.bind(app)
            );

        } else {
            ele.dispatchEvent(nbEvent('result', app));
        }
    } else {
        ele.dispatchEvent(nbEvent('soft-result', app));
    }
}

destroy()

This method will remove the event listeners the widget attached to the field and form as well as remove changes it made to the DOM.

This method is called by fields.unregisterListener(ele).

FieldsStore

 

The field store manages all the registered fields and contains the FieldListener objects. It can be accessed in the browser from window._nb.fields.

all()

This method will return an array containing all the registered fields as FieldListener objects.

_nb.fields.all()
// [FieldListener, ...]

get(ele)

This method will return an array containing FieldListener objects for a specific element node.

var ele = document.querySelector('#my-field');
_nb.fields.get(ele)
// [FieldListener]

initListeners()

This method is called after the page is loaded to register fields when autoFieldHookup is enabled. It will look for any fields using the email type, containing the data-nb attribute or contain the selector specified in selector option.

_nb.fields.initListeners()

registerListener(ele [, broadcastRegisration])

This method will register the specified element with the widget. It accepts two arguments, the first being the node to register and the second being an optional boolean. When set to false, the second argument allows you to silently register a node without it broadcasting the nb:registered event. This argument defaults to true.

// Second argument is optional, it defaults to true
var ele = document.querySelector('#my-field', true)
_nb.fields.registerListener(ele)

removeListeners()

This method will unregister all the fields from the widget. (See unregisterListener)

_nb.fields.removeListeners()

unregisterListener(ele)

This method will unregister the specified field. It will call the destroy method in the FieldListener object.

var ele = document.querySelector('#my-field', true)
_nb.fields.unregisterListener(ele)

Result

 

This object offers several helper methods for working with the response from the API. Every time an API request is completed (successfully or erroneously) a new Result object is created.

response

This property contains the object returned by the API.

getResult()

This method returns the text based result code returned by the API. The same as doing this.response.result.

getNumericCode()

This method returns the integer code for the result returned by the API.

getTransactionId()

This will return the transaction id for this request. It can be used to confirm the data was verified with the confirm endpoint.

getConfirmationToken()

This will return the confirmation token for this request. It can be used to confirm the data was verified with the confirm endpoint.

isError()

This method will return true if the request failed or if the API returned an error. Otherwise, this method will return false.

is(codes)

This method will return true if the verification result is equal to the specified code(s). It accepts both text and numeric result codes either as a single code or as an array of codes.

result.is('valid'); // Returns true if the result is 'valid'
result.is(0); // Returns true if the result is 'valid'
result.is(['valid','catchall']); // Returns true if the result is either 'valid' or 'catchall'
result.is([0,3]); // Returns true if the result is either 'valid' or 'catchall'

not(codes)

This method will return true if the verification result differs than the specified code(s). It accepts both text and numeric result codes either as a single code or as an array of codes.

result.not('invalid'); // Returns true if result anything but 'invalid'
result.not(1); // Returns true if result anything but 'invalid'
result.not(['invalid','disposable']); // Returns true if result anything other than 'invalid' or 'disposable'
result.not([1,2]); // Returns true if result anything other than 'invalid' or 'disposable'

Settings

 

The settings object controls the widget's settings. It's created during the initialization of the widget with the _NBSettings object. Modifying the settings after initialization may break some functionality.

Events

 

Events emitted from the widget are prefixed with the nb: namespace. Each event will contain additional relevant information in the details property of the event object.

nb:registered

 

Fired from the fields when they're registered with the widget when the autoHookup configuration is enabled or if the registration argument for registerField is true. Used to register the feedback events on automatically registration.

field.addEventListener('nb:registration', function(e) {
    // Get the ID for this field
    var id = e.details.id;
});

nb:result

 

Fired from the field when a verification request is completed. This event will contain the field id, a readable error message (if an error occurred), as well as the result object.

field.addEventListener('nb:result', function(e) {
  
    // Get the ID for this field
    var id = e.details.id;
  
    // Get error message
    var error = e.details.error;
  
    // Get result object
    var result = e.details.result;
});

nb:soft-result

 

Fired from the field when its input isn't a syntactically valid email (e.g. a missing @ character or incomplete domain name). This is useful to prompt the user for a properly formatted email.

field.addEventListener('nb:soft-result', function(e) {
  
    // Get the ID for this field
    var id = e.details.id;
});

nb:clear

 

Fired from the field when its input is being manipulated. This can be useful for hiding the feedback while the user is typing into the field. This event is also fired when an error is returned by the API.

field.addEventListener('nb:clear', function(e) {
    // Get the ID for this field
    var id = e.details.id;
  
    // Check for an API error
    if (e.detail.result && e.detail.result.isError()) {
        // Get error message
    	  var error = e.details.error;
    }
});

nb:loading

 

Fired from the field when the verification request starts. Can be used to display a loading indicator to the user. A nb:result event will be fired once the verification request has been completed.

field.addEventListener('nb:loading', function(e) {
  
    // Get the ID for this field
    var id = e.details.id;
});

nb:submit

 

Fired from the form when ajaxMode is enabled. This event is to be used for submitting ajax style forms. It’s important to use this event to process the sending of your form rather than the native submit event.

field.addEventListener('nb:submit', function(e) {
  
    // Get the ID for this field
    var id = e.details.id;
  
    // Get error message
    var error = e.details.error;
  
    // Get result object
    var result = e.details.result;
});

Widget Errors

 

Timeout

Timeouts will occur from time to time due to the nature of real-time verification. These are only an issue if they occur frequently or with larger email providers such as Gmail, Yahoo and the like. You can adjust the timeout with the timeout setting if this is happening too frequently or if the default timeout is too long.

Insufficient Credits

This will occur when you no longer have credits in your account. You can purchase additional credits within the dashboard or switch to monthly billing to avoid the issue altogether.

Bad Referrer

A bad referrer means the domain in which the widget is being used on is not authorized to use it. This is controlled from the “Trusted Domains” section within the widgets settings through the dashboard.

Throttling

Throttling is a protection method to curb and prevent abuse of your forms. This can be adjusted in the “Throttling” section of the widgets settings within the dashboard.

/poe/confirm

 

Query Auth

 Authentication is required for this endpoint.
posthttps://api.neverbounce.com/v4/poe/confirm
curl --request POST\
  --url https://api.neverbounce.com/v4/poe/confirm\
  --data key={api_key}\
  --data email={email}\
  --data transaction_id={transaction_id}\
  --data confirmation_token={confirmation_token}
  --data result={result}
<?php

// Authenticate requests
\NeverBounce\Auth::setApiKey($api_key);

// Confirm submission
$poe = \NeverBounce\PoE::confirm(
  $_POST['email'], 
  $_POST['nb-confirmation-token'], 
  $_POST['nb-transaction-id'], 
  $_POST['nb-result']
);
// Initialize NeverBounce client
const client = new NeverBounce({apiKey: myApiKey});

// Get the job status
client.jobs.poe(
  req.body['email'], 
  req.body['nb-confirmation-token'], 
  req.body['nb-transaction-id'], 
  req.body['nb-result']
).then(
    resp => // Handle successful response,
    err => // Handle errors
);
# Create sdk client
client = neverbounce_sdk.client(api_key='api_key')

# Confirm frontend widget
resp = client.poe_confirm(
    email='support@neverbounce.com',
    transaction_id='NBPOE-TXN-5942940c09669',
    confirmation_token='e3173fdbbdce6bad26522dae792911f2',
    result='valid'
)
// Instantiate wrapper
client := neverbounce.New("api_key")

// Confirm the client side verification
confirmInfo, err := client.POE.Confirm(&nbModels.POEConfirmRequestModel{
  Email:             "support@neverbounce.com",
  ConfirmationToken: "1341234jkh12h34lb2134b143",
  TransactionID:     "1340813265013984123",
  Result:            "valid",
})
# Instantiate API client
client = NeverBounce::API::Client.new(api_key: "api_key")

# Confirm verification
resp = client.poe_confirm(
  email: "alice@isp.com", 
  transaction_id: "NBTRNS-abcdefg123456", 
  confirmation_token: "abcdefg123456", 
  result: "valid"
)
// Create SDK object
var sdk = new NeverBounceSdk("api_key");

// Create poe confirm model
 var model = new POEConfirmRequestModel();
model.email = "support@neverbounce.com";
model.confirmation_token = "e3173fdbbdce6bad26522dae792911f2";
model.transaction_id = "NBPOE-TXN-5942940c09669";
model.result = "valid";

// Confirm frontend verification
POEConfirmResponseModel resp = sdk.POE.Confirm(model).Result;
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  'status': 'success', 
  'token_confirmed': true, 
  'execution_time': 35
}

Body Params

email
string
required
transaction_id
string
required
confirmation_token
string
required
result
string
required
 

This endpoint uses the same authentication scheme as the rest of our API. The public API key used by the widget will not work for this endpoint.

This endpoint provides an extra layer of protection by confirming that the email you received was verified by NeverBounce. In most use cases the widget on its own provides enough protection against bad emails. However, an advanced user can disable or modify the script, as is the case with any client-side script. If you have control over the server-side script that processes the form request you can use this endpoint to confirm that the email supplied was verified.

Every verification performed by the widget is accompanied by a "transaction id" and "confirmation token". These are both accessible from the Result Object and in the form as the nb-transaction-id and nb-confirmation-token fields. These two parameters can be passed to this endpoint alongside the email that was submitted to confirm if this is the same email we verified or not.