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.

  1. Submit single email address at a time. (Verify an email)

  2. 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_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.

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,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.

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 :

  1. Failed to establish the connection with neverbounce.com

  2. Connection established but no data retrived from neverbounce.com

  3. Values provided for api_username and api_secret_key are 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 neverbounce

You can also look for information at:

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.