neverbounce - neverbounce.com email verification API integration module
Version 0.03
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();
The neverbounce is a class implementing API integration to neverbounce.com for verifying email addresses submitted to it.
neverbounce
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
$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.
access_token
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
access token
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.
email
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 )
+-----------+---------------+-----------------------------------+---------------------------------------------------+ |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.
+---------------+-------------------------------------------+ | Value | Description | +---------------+-------------------------------------------+ | 0 | No additional details | | 1 | Provided email failed the syntax check | +---------------+-------------------------------------------+
With the NeverBounce API you are able to verify your existing contact lists without ever needing to upload a list to the dashboard.
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.
413 Request Entity Too Large
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.
input_location
input
filename
The permited value for the parameter input_location is either 0 or 1.
If input_location is set as 0, then value of input is expected to be the a URL to the list.
If input_location is set as 1, then value of input is expected to be the a URL encoded string of the contents of the list.
filename is optional, but do suggest supplying it as it will be useful for identifying your list in the user account dashboard of the neverbounce.com.
( 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.
job_id
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.
( 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.
status
codes
stats
processed
billable
Once the status value is 4 you're ready to retrieve the results.
4
+---------------+--------------------------------------------------------------------------------------------+ | 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> | +---------------+--------------------------------------------------------------------------------------------+
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.
valids
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.
invalids
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.
catchall
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.
disposable
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.
unknown
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.
duplicates
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.
textcodes
+---------------+-------------------------------------------------------------------------------+ |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:
$response{data}{list}
valid@example.com,valid invalid@example.com,invalid
The 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.
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.
( 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' } )
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.
resp_status
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.
request_data
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 :
neverbounce-
Failed to establish the connection with neverbounce.com
Connection established but no data retrived from neverbounce.com
Values provided for api_username and api_secret_key are invalid or expired.
api_username
api_secret_key
In this case you can find the error in your server error logs (if it's present);
Manu Mathew, <whitewind at cpan.org>
<whitewind at cpan.org>
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.
bug-neverbounce at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc neverbounce
You can also look for information at:
GitHub: Development tracker (report bugs and suggesitions here)
https://github.com/manukeerampanal/neverbounce
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=neverbounce
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/neverbounce
CPAN Ratings
http://cpanratings.perl.org/d/neverbounce
Search CPAN
http://search.cpan.org/dist/neverbounce/
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.
To install neverbounce, copy and paste the appropriate command in to your terminal.
cpanm
cpanm neverbounce
CPAN shell
perl -MCPAN -e shell install neverbounce
For more information on module installation, please visit the detailed CPAN module installation guide.