Name
neverbounce - neverbounce.com email verification API integration module
VERSION
Version 0.05
Synopsis
use neverbounce;
my $neverbounce = neverbounce->new(api_username => 'DwxtvXg0', api_secret_key => 'WsryzB2F7#6RcH$') or die "Failed to initialize";
my %email_verify_result = $neverbounce->nb_verify_email(email => 'test@example.com');
#OR
use neverbounce;
my $neverbounce = neverbounce->new(api_username => 'DwxtvXg0', api_secret_key => 'WsryzB2F7#6RcH$')
or die "Failed to initialize";
my %email_verify_send = $neverbounce->nb_email_list_batch_send(
input_location => 0,
input => 'http://www.example.com/folder/file_123_999.csv',
filename => 'NB_01_01_2016.csv'
);
my %email_verify_send_check = $neverbounce->nb_email_list_batch_check(job_id => '123456');
my %email_verify_send_result = $neverbounce->nb_email_list_batch_result(job_id => '123456');
my %result_codes = $neverbounce->nb_result_code();Description
The neverbounce is a class implementing API integration to neverbounce.com for verifying email addresses submitted to it.
Neverbounce.com provide 2 methods to submit email ids to them.
Submit single email address at a time. (Verify an email)
Batch email address submission. (Verifying a list)
In the 2nd section, we can submit data in 2 means.
Store the file to a csv list and store it to a place where it can be accessed publically. Then submit the URL for file to the neverbounce.comIn this method, the neverbounce.com will access the '.csv' file from their part to process it.
Directly submit the entire list as POST method to the neverbounce.com
API Initiation and Authentication
$neverbounce = neverbounce->new( %options ) or die "Failed to initialize";This method intiates the request to the neverbounce.com and gets the access_token which is required for further processing. The access_token is normally valid for an hour and used for any number of requests.
The following options correspond to attribute methods described below:
+---------------+----------------------------------------+
|Key | Value |
+---------------+----------------------------------------+
|api_username | <API Username> |
|api_secret_key | <API Secret Key> |
+---------------+----------------------------------------+Nevebounce uses OAuth 2.0 authentication model. This requires you to make an initial request for an access token before making verification requests. API Username and API Secret Key are available at 'API Credentials' in the user account of neverbounce.com
Verifying an Email
my %email_verify_result = $neverbounce->nb_verify_email( email => 'test@example.com' );This method is used to validate an email address in realtime. The parameter email is mandatory to process this function.
The response for the function will be returned as a hash and they are,
(
resp_status => 'success', # status for the request. Expected values are 'success' and 'error'
data => {
result_code => __,
# The result code. Expected Values : 0 / 1 / 2 / 3 / 4
result_text_code => __,
# The text code for the result_code. Expected Values : valid / invalid / disposable / catchall /unknown
result_description => __,
# The description for the result code
result_safe_to_send => __,
# The recommendation regarding whether to use this email addres for sending email
result_details_code => __,
# Reson Code for error. Expected Values : 0 / 1
result_details_description => __,
# Description for 'result_details_code'
neverbounce_execution_time => __
# Time consumed by neverbounce.com for processing request
},
request_data => __
# this contains Dumper() value of HTTP request - response between the neverbounce.com and requesting server
)Result Code
+-----------+---------------+-----------------------------------+---------------------------------------------------+
|Text Code | Numeric Code | Description | Safe to Send? |
+-----------+---------------+-----------------------------------+---------------------------------------------------+
|valid | 0 | Verified as real address | Yes |
|invalid | 1 | Verified as not valid | No |
|disposable | 2 | A temporary, disposable address | No |
|catchall | 3 | A domain-wide setting (learn more)| Maybe. Not recommended unless on private server |
|unknown | 4 | The server cannot be reached | No |
+-----------+---------------+-----------------------------------+---------------------------------------------------+
You can also find the result_code data from the following link : https://neverbounce.com/help/getting-started/result-codes/Please Note: Results are not available via the user dashboard and should be stored on the user's requesting end.
Result Detail Codes
+---------------+-------------------------------------------+
| Value | Description |
+---------------+-------------------------------------------+
| 0 | No additional details |
| 1 | Provided email failed the syntax check |
+---------------+-------------------------------------------+Verifying a List
With the NeverBounce API you are able to verify your existing contact lists without ever needing to upload a list to the dashboard.
Adding a List
To get started you first need to aggregate your data into a CSV format. Each row can only contain a single email and all emails should be in the same column.
Click following link to learn more about formatting your list. (https://neverbounce.com/help/getting-started/uploading-a-file/)
Once aggregated this list can be submitted either directly as a URL encoded string or by submitting a public URL to the CSV. For larger lists the latter method is preferred. If you receive a 413 Request Entity Too Large http error, you should try submitting a public URL to the CSV instead.
When you submit a list via the API the verification process will start automatically. If your credit balance is insufficient the verification of your list will fail. You can purchase credits in bulk from the dashboard or submit a request(https://app.neverbounce.com/settings/billing) to use neverbounce.com monthly billing option. You can also choose to run a free analysis rather than verifying your list, see https://neverbounce.com/help/api/running-a-free-analysis/.
my %email_verify_send = $neverbounce->nb_email_list_batch_send( %option );This method is used when there is more than one email address to be verified at a single request. The options permitted are as follows :
%option = (
input_location => 0,
input => 'http://www.example.com/folder/file_123_999.csv',
filename => 'NB_01_01_2016.csv'
);The parameters input_location and input are mandatory and filename is optional.
The permited value for the parameter
input_locationis either 0 or 1.If
input_locationis set as 0, then value ofinputis expected to be the a URL to the list.If
input_locationis set as 1, then value ofinputis expected to be the a URL encoded string of the contents of the list.filenameis optional, but do suggest supplying it as it will be useful for identifying your list in the user account dashboard of the neverbounce.com.
The response for the function will be returned as a hash and they are,
(
resp_status => 'success', # status for the request. Expected values are 'success' and 'error'
data => {
job_status => __,
# Processing status of the current submitted email batch file. Response will be '0'
job_id => __,
# Job id assigned by the neverbounce.com for the submitted process
neverbounce_execution_time => __
# Time consumed by neverbounce.com for processing request
},
request_data => __
# this contains Dumper() value of HTTP request - response between the neverbounce.com and requesting server
)Once you get a response you'll want to store the value of job_id, as it will be used to check the status and eventually retrieve the results. Now you're ready to start checking the status of the verification.
Checking the status
Now that your list is running, you will need to poll the API and check the status periodically. For smaller lists (<50k) polling every 5-10 seconds is acceptable, but for larger lists (>50k) you'll want to poll less frequently.
my %email_verify_send_check = $neverbounce->nb_email_list_batch_check(job_id => '123456');This method is used to check the processing status of the email list batch file. The paramtere job_id is mandatory for the function to process. Click Here to know how to retrive the value for job_id.
The response for the function will be returned as a hash and they are,
(
resp_status => 'success', # status for the request. Expected values are 'success' and 'error'
data => {
status => __,
# The processing status for the requested job. Expected values: 0 / 1 / 2 / 3 / 4 / 5
status_desc => __,
# The descripton for the parameter 'status'
id => __,
type => __,
input_location => __,
orig_name => __,
created => __,
started => __,
finished => __,
file_details => __,
job_details => __,
neverbounce_execution_time => __, # Time consumed by neverbounce.com for processing request
stats => {
total => __, # total records submitted
processed => __, # total records processed
valid => __, # no of valid records among processed records
invalid => __, # no of invalid records among processed records
bad_syntax => __, # no of bad syntaxed records among processed records
catchall => __, # no of catchall records among processed records
disposable => __, # no of disposable records among processed records
unknown => __, # no of unknown records among processed records
duplicates => __, # no of duplicate records among processed records
billable => __, # no of billable records among processed records
job_time => __, # time used to process the processed records
}
},
request_data => __
# this contains Dumper() value of HTTP request - response between the neverbounce.com and requesting server
)In the response, the status parameter will indicate what the list is currently doing. You can find a table of status codes below. Typically status will be the only parameter you will need to watch. However, you may find the stats object useful for seeing a breakdown of the results in your list while it's processing. You can also use the processed and billable values in the stats object to track the progress of the verification.
Once the status value is 4 you're ready to retrieve the results.
Status Codes
+---------------+--------------------------------------------------------------------------------------------+
| Value | Description |
+---------------+--------------------------------------------------------------------------------------------+
| 0 | Request has been received but has not started idexing |
| 1 | List is indexing and deduping |
| 2 | List is awaiting user input (Typically skipped for lists submitted via API) |
| 3 | List is being processed |
| 4 | List has completed verification |
| 5 | List has failed (Click following link to learn how to fix a failed list) |
| | <https://neverbounce.com/help/getting-started/uploading-a-file/#fixing-a-failed-list> |
+---------------+--------------------------------------------------------------------------------------------+Retrieving the Results
Once the "Checking the status" returns the value for the parameter status as 4, we can retive the results from the neverbounce.com.
my %email_verify_send_result = $neverbounce->nb_email_list_batch_result( %option );This method is used to retirive the result from the neverbounce.com. The options permitted are as follows :
%option = (
job_id => '12345',
valids => 1,
invalids => 1,
catchall => 1,
disposable => 1,
unknown => 1,
duplicates => 1,
textcodes => 1,
)The parameter job_id is manadatory. The rest are optional.
valids=> values permitted are 0 and 1. If set 0, the reslut received from the server will omit valid values. The default value is 1.invalids=> values permitted are 0 and 1. If set 0, the reslut received from the server will omit invalid values. The default value is 1.catchall=> values permitted are 0 and 1. If set 0, the reslut received from the server will omit catchall values. The default value is 1.disposable=> values permitted are 0 and 1. If set 0, the reslut received from the server will omit disposable values. The default value is 1.unknown=> values permitted are 0 and 1. If set 0, the reslut received from the server will omit unknown values. The default value is 1.duplicates=> values permitted are 0 and 1. If set 0, the reslut received from the server will omit duplicate values. The default value is 1.textcodes=> values permitted are 0 and 1. If set 0, the reslut received from the server will give numeric result codes. Else it will be text code alternate to numeric code. Click here to know the definition for the result codes. The default value is 1.
+---------------+-------------------------------------------------------------------------------+
|Parameter | Value |
+---------------+-------------------------------------------------------------------------------+
|valids | Include valid emails |
|invalids | Include invalid emails |
|catchall | Include catchall emails |
|disposable | Include disposable emails |
|unknown | Include unknown emails |
|duplicates | Include duplicated emails (duplicates will have the same verification result) |
|textcodes | Result codes will be returned as english words instead of numbers |
+---------------+-------------------------------------------------------------------------------+Example Response:
(
resp_status => 'success',
data => {
list => $result->{_content}
},
request_data => Dumper($result)
)Example $response{data}{list} will be as follows:
valid@example.com,valid
invalid@example.com,invalidThe data will be returned in a CSV format with the last column containing the result codes. This will look familiar if you've verified a list through the dashboard.
Retrieving Results Codes
my %result_codes = $neverbounce->nb_result_code();This method can be used to retrive the result codes, it's text code, descriptions and recommendation regarding whether an email id get verified.
The response for the function will be returned as a hash and they are,
(
0 => {
text_code => 'valid',
numeric_code=> '0',
description => 'Verified as real address',
safe_to_send=> 'Yes'
},
1 => {
text_code => 'invalid',
numeric_code=> '1',
description => 'Verified as not valid',
safe_to_send=> 'No'
},
2 => {
text_code => 'disposable',
numeric_code=> '2',
description => 'A temporary, disposable address',
safe_to_send=> 'No'
},
3 => {
text_code => 'catchall',
numeric_code=> '3',
description => 'A domain-wide setting',
safe_to_send=> 'Maybe. Not recommended unless on private server'
},
4 => {
text_code => 'unknown',
numeric_code=> '4',
description => 'The server cannot be reached',
safe_to_send=> 'No'
},
'valid' => {
text_code => 'valid',
numeric_code=> '0',
description => 'Verified as real address',
safe_to_send=> 'Yes'
},
'invalid' => {
text_code => 'invalid',
numeric_code=> '1',
description => 'Verified as not valid',
safe_to_send=> 'No'
},
'disposable'=> {
text_code => 'disposable',
numeric_code=> '2',
description => 'A temporary, disposable address',
safe_to_send=> 'No'
},
'catchall' => {
text_code => 'catchall',
numeric_code=> '3',
description => 'A domain-wide setting',
safe_to_send=> 'Maybe. Not recommended unless on private server'
},
'unknown' => {
text_code => 'unknown',
numeric_code=> '4',
description => 'The server cannot be reached',
safe_to_send=> 'No'
}
)Error Handling
You can identify error from the response hash you receive when a function is being called. To make sure your request is a success, check the value for the parameter resp_status. It will be success, if your request processed succesfully. If it's error, Then your request has failed to processed. You can find the error data from the response.
The response will be as follows when an error occur:
(
resp_status => 'error',
data => {
error => __, # defiens error type
error_description => __ # Describes the reson for the error
},
request_data => __
# this contains Dumper() value of HTTP request - response between the neverbounce.com and requesting server
)The parameter request_data will be filled with value when the request is passed to never bounce. Else it will be left blank. It will be mostly left bank only when you missed some mandatory values.
There is a condition when the module returns nothing. It will be occured when you call the method neverbounce-new()> and there the method faces following situations :
Failed to establish the connection with neverbounce.com
Connection established but no data retrived from neverbounce.com
Values provided for
api_usernameandapi_secret_keyare invalid or expired.
In this case you can find the error in your server error logs (if it's present);
AUTHOR
Manu Mathew, <whitewind at cpan.org>
BUGS
Please report any bugs or feature requests to bug-neverbounce at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=neverbounce. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc neverbounceYou can also look for information at:
GitHub: Development tracker (report bugs and suggesitions here)
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
LICENSE AND COPYRIGHT
Copyright 2016 Manu Mathew.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.
If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.
This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.
This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.
Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.