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.
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
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.
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
}
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
<?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.
/check
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.
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.
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.
/create
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.
/parse
This endpoint allows you to parse a job created with auto_parse
disabled. You cannot reparse a list once it's been parsed.
/start
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
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.
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.
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
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
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.
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, otherwise 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).
binary_operators_type
Determines how Yes/No columns are represented. Available settings are:
BIN_1_0
= 1/0 (default)BIN_Y_N
= Y/NBIN_y_n
= y/nBIN_yes_no
= yes/noBIN_Yes_No
= Yes/NoBIN_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\nLINEFEED_0A
= \nLINEFEED_0D
= \r
/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
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.