This is the official NeverBounce API PHP wrapper. It provides helpful methods to quickly implement our API in your existing php applications. ###Requirements
- PHP 5.4 or greater
- PHP JSON extension
- PHP cURL extension
Be sure to familiarize yourself with the API by visiting the documentation.
This package takes advantage of composer's autoloading features, following the PSR-4 guidelines.
To install using composer you can run
composer require neverbounce/neverbounce-php
Or add this to your composer.json
{
"require": {
"neverbounce/neverbounce-php":"3.0.*"
}
}
You can clone the repo directly and include the files yourself via an auto loader. Keep in mind that this package does follow the PSR-4 spec.
git clone https://github.com/creavos/NeverBounceAPI-PHP
With our PHP wrapper authentication can be done by calling the NB_Auth
class and running the auth
method. Don't worry about passing a router or version if you do not have these details. Make sure to do this before making any requests with the wrapper or you will receive an authentication error. Placing this in the startup or config of your application is recommended.
Find your credentials here
// API_SECRET_KEY Your API secret key
// API_KEY Your API username
// ROUTER Your API sub domain http://<route>.neverbounce.com
// VERSION The api version to use
\NeverBounce\API\NB_Auth::auth(<API_SECRET_KEY>, <API_KEY>, [<ROUTER>, [<VERSION>]]);
The authentication class also allows you to set a hard connection timeout (CURLOPT_TIMEOUT). By default the timeout is set to 0
effectively meaning a timeout is not set. A hard timeout will produce an exception when it occurs. To set a hard connection timeout use the following sample:
// Set cURL timeout
\NeverBounce\API\NB_Auth::setTimeout(<TIME_IN_SECONDS>);
When using the single verification it is recommended to set a verification timeout using the verify
method described in the Single
section below. The verification timeout will produce a more graceful response.
Once you've authenticated you can use the endpoints freely. To validate an email use the verify
method in the NB_Single
class. The result is stored in the response
property in this class, you can also find the raw JSON response in the response_raw
property. We have included two additional methods in this class so you can easily check the result or get a human readable result.
// Verify an email
// VERIFICATION_TIMEOUT is optional. You can specify a maximum amount of time in seconds before we respond
// (this is a soft limit and may exceed the limit by several milliseconds)
$email = \NeverBounce\API\NB_Single::app()->verify(<EMAIL>[, <VERIFICATION_TIMEOUT>]);
var_dump($email->response);
object(stdClass)#5 (4) {
["success"]=>bool(true)
["result"]=>int(0)
["result_details"]=>int(0)
["execution_time"]=>float(1.5955789089203)
}
###is() This method will check to see if the the validation result matches the desired result code and will return either true or false. It accepts result codes in either string, integer or array formats.
$email = \NeverBounce\API\NB_Single::app()->verify(<EMAIL>);
// Returns true if email is valid
$email->is('valid');
$email->is(0);
// Returns true if email is valid or catchall
$email->is(['valid', 'catchall']);
$email->is([0,3]);
####Accepted Codes
text | integer |
---|---|
valid | 0 |
good (alias) | 0 |
invalid | 1 |
bad (alias) | 1 |
disposable | 2 |
catchall | 3 |
unknown | 4 |
###defintion() This method returns a human readable string for the validation result. The strings returned are 'Valid', 'Invalid', 'Disposable', 'Catchall', and 'Unknown'.
$email = \NeverBounce\API\NB_Single::app()->verify(<EMAIL>);
// Returns 'Valid' if email is valid
$email->definition();
The account class can be accessed by calling the check
method within the NB_Account
class. This will give you a quick overview of your account. As with the Single endpoint you can access the result via the response
property and the raw JSON via the response_raw
property. We have also provided a couple helpers to make it easier to extract the data.
$account = \NeverBounce\API\NB_Account::app()->check();
var_dump($account->response);
object(stdClass)#5 (5) {
["success"]=>bool(true)
["credits"]=>string(7) "9085992"
["jobs_completed"]=>string(2) "39"
["jobs_processing"]=>string(1) "4"
["execution_time"]=>float(0.064954996109009)
}
###balance() This returns your current credit balance.
$account = \NeverBounce\API\NB_Account::app()->check();
var_dump($account->balance());
###jobs_completed() This returns how many completed jobs that you have run through the bulk endpoint or through the dashboard
$account = \NeverBounce\API\NB_Account::app()->check();
var_dump($account->jobs_completed());
###jobs_processing() This returns how many running jobs that you have processing through the bulk endpoint or through the dashboard
$account = \NeverBounce\API\NB_Account::app()->check();
var_dump($account->jobs_processing());
The bulk class includes several methods for interacting with bulk validations, the same validations that are done by uploading a CSV to the dashboard.
###get()
This method returns all existing jobs in your account, including any and all jobs you have run through the dashboard. These jobs will be returned in ascending order from your earliest job to your latest job. The jobs can be accessed in the jobs
property, or by using our helper functions to navigate this array. Each job is stored as a new NB_Job
object in this array.
use \NeverBounce\API\NB_Bulk;
$job = NB_Bulk::app()->get();
var_dump($jobs->jobs);
###retrieve()
This method will return only the results of the jobs you specify. When you already know the id of the job or jobs you need to query for, this method will return the result faster. You can supply a single id as an integer or supply multiple ids in an array. These job(s) will be stored in the jobs
property as NB_Job
objects just as they would be using the get
method.
use \NeverBounce\API\NB_Bulk;
// Single ID
$job = NB_Bulk::app()->retrieve(<JOB_ID>);
var_dump($job->jobs);
// Multiple ID's
$jobs = NB_Bulk::app()->retrieve(array(<JOB_ID>,<JOB_ID>));
var_dump($jobs->jobs);
###all()
This will return the jobs
array. It's the same as calling NB_Bulk::app()->jobs
.
use \NeverBounce\API\NB_Bulk;
$job = NB_Bulk::app()->get();
var_dump($jobs->all());
###first()
This will return the first item in the jobs
array. It's the same as NB_Bulk::app()->jobs[0]
.
use \NeverBounce\API\NB_Bulk;
$job = NB_Bulk::app()->get();
var_dump($jobs->first());
###desc()
This will perform a rsort
on the jobs
property reversing the sorting of the array. Useful for when you want your newest job to appear first and oldest job to appear last in the array. This method returns itself so it is chainable with first
or all
.
use \NeverBounce\API\NB_Bulk;
$job = NB_Bulk::app()->get();
// Returns newest job
var_dump($jobs->desc()->first());
###select()
This method will allow you to select a specific job from the jobs
array by passing the desired job's ID. If the job doesn't exist it will return false.
use \NeverBounce\API\NB_Bulk;
$job = NB_Bulk::app()->get();
var_dump($jobs->select(<JOB_ID>));
###create()
This method allows you to start new bulk validation jobs. Input can be provided either directly by getting the contents of a file or by passing a URL for the file. You can also specify a filename for the job to appear as in the dashboard, if one isn't provided uniqid()
will be used as the filename. This function will fetch
the job details open success.
use \NeverBounce\API\NB_Bulk;
$job = NB_Bulk::app()->create(<INPUT>, <INPUT_LOCATION>[, <FILENAME>]);
var_dump($job->first());
###sample()
This method allows you to start a free analysis on your data. Read more about the list analysis (here)[https://docs.neverbounce.com/#methods-bulk-free-analysis]. This function takes the same parameters as the create
method above. Once you have completed an analysis you can then run a full validation using the start
method.
use \NeverBounce\API\NB_Bulk;
$job = NB_Bulk::app()->sample(<INPUT>, <INPUT_LOCATION>[, <FILENAME>]);
var_dump($job->first());
####Input & Input Location
The bulk
endpoint allows email lists to be passed to it two different ways using the input_location
parameter.
#####Remote URL
Using a remote url allows you to host the file and provide us with a direct link to it. This can be done with any protocol supported by cURL, we suggest using either http
, https
, ftp
, ftps
or sftp
. When using a url that requires authentication be sure to pass the username and password in the actual url. When using sftp
keep in mind that we do not currently support key based authentication.
use \NeverBounce\API\NB_Bulk;
$input = 'https://example.com/email_list.csv';
$job = NB_Bulk::app()->create($input, NB_Bulk::REMOTE_URL);
var_dump($job->first());
######Valid URLs
# FTP With Authentication
ftp://name:[email protected]:21/full/path/to/file
# HTTP Request
http://example.com/full/path/to/file
# HTTP Basic Authentication
http://name:[email protected]/full/path/to/file
#####Supplied Data
Supplying the data directly gives you the option to dynamically create email lists on the fly. To do this either pass the emails separated with line breaks (\r\n
or \n
) or by passing csv formatted data (comma, semi-colon, space or tab delimeters). When using this method be sure that the data is HTTP encoded to prevent any mangling of the data.
use \NeverBounce\API\NB_Bulk;
$input = file_get_contents('email_list.csv');
$job = NB_Bulk::app()->create($input, NB_Bulk::SUPPLIED_DATA);
var_dump($job->first());
######Raw text Input (New lines)
######Raw CSV Input
ID, Email, Name, Department\n
1, [email protected], Joe, Accounting\n
2, [email protected], Alice, Accounting\n
3, [email protected], Tom, Billing\n
###start()
This method allows you to run a full validation on a job you have started with the sample
method.
use \NeverBounce\API\NB_Bulk;
NB_Bulk::app()->start(<JOB_ID>);
###download()
The download method lets you download a job's data once it has completed. It will return the data in the form of CSV data. You can optionally specify options in an array to download only certain items from the validated list.
use \NeverBounce\API\NB_Bulk;
$job = NB_Bulk::app()->download(<JOB_ID>);
var_dump($job);
####With Options
In the following example you will see the defaults used in the download options. Setting any of these to false will remove it from the downloaded data.
use \NeverBounce\API\NB_Bulk;
$options = array(
'valids' => true
'invalids' => true,
'catchall' => true,
'disposable' => true,
'unknown' => true,
'duplicates' => true,
'textcodes' => true
);
$job = NB_Bulk::app()->download(<JOB_ID>, $options);
var_dump($job);
###delete()
This action is not able to be undone Removes the job data from the NeverBounce system. Once removed the data will no longer be available on our system and can not be restored.
use \NeverBounce\API\NB_Bulk;
$job = NB_Bulk::app()->delete(<JOB_ID>);
var_dump($job);
The NB_Job
class offers helpers to making working with individual jobs easier. It abstracts the job data returned by the status
and list_user_jobs
endpoints. Job data is accessible using the following properties.
object(NeverBounce\API\NB_Job)#88 (15) {
["id"]=>int(5302)
["purchased"]=>bool(true)
["type"]=>int(0)
["input_location"]=>int(2)
["started"]=>int(1426600830)
["filename"]=>string(14) "list3500_a.csv"
["finished"]=>bool(true)
["state"]=>int(4)
["total"]=>int(3500)
["processed"]=>int(3500)
["valid"]=>int(1298)
["invalid"]=>int(2114)
["catchall"]=>int(42)
["disposable"]=int(0)
["unknown"]=>int(46)
}
###percentage()
This method will calculate the percentage of the desired property. It defaults to a two decimal number (000.00). If the job is not processing or completed then this will return null
.
$job->percentage(<PROPERTY>[, <DECIMALS>]);
####Acceptable Properties
total
processed
valid
invalid
catchall
disposable
unknown
###total()
This method gives you a safe way to return the totals. If the job is not yet processing or completed then it will return null
for the value. Accessing the property directly will return 0
.
$job->total(<PROPERTY>);
####Acceptable Properties
total
processed
valid
invalid
catchall
disposable
unknown
###download()
This is a wrapper of the NB_Bulk::app()->download()
method. It fills out the ID for you and accepts the same options array as an argument.
$job->download([<options>]);
###delete()
This action is not able to be undone
This is a wrapper of the NB_Bulk::app()->delete()
method. It will fill out the ID for you. Keep in mind this can not be undone.
$job->delete();
This API wrapper will throw a NB_Exception
whenever it encounters an error. It is recommended to place all requests within try/catch blocks to gracefully catch these exceptions.
An exception will be thrown in the following instances
- The cURL extension is not found
- The JSON extension is not found
- You do not supply a secret key to
NB_Auth::auth()
- You do not supply an app id to
NB_Auth::auth()
- You supply the wrong credentials to
NB_Auth::auth()
, a standard OAuth 2.0 error will be returned - You did not generate an access_token before making a request
- You do not have sufficient credits to complete the request
- You have supplied an invalid job ID (left from v1)
- The request is malformed (verify that you are running on the correct API version)
- Your access token has expired or is invalid (Authorization failure)
- Or in the event of an internal API error
#####v3.0.0
- With version 3.0 of the API, we have introduced OAuth 2.0 to replace our authentication system. For this reason we have discontinued both v1.x and v2.x APIs.