neverbounce-sdk 4.3.0

Official Python SDK for the NeverBounce API

Welcome to NeverBounce’s Python SDK! We hope that it will aid you in consuming our service. Please report any bugs to the github issue tracker and make sure you read the documentation before use.

Installation

The preferred method of installation is with pip in a virtual environment:

pip install neverbounce_sdk

If you must use easy_install, you may. If you’d like to install for local development:

git clone [e-mail]:NeverBounce/NeverBounceApi-Python.git
cd NeverBounceApi-Python
pip install -e .

This will install neverbounce_sdk into the active environment in editable mode.

Usage

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](https://app.neverbounce.com/apps/custom-integration/new).

The NeverBounce Python SDK provides a simple interface by which to interact with NeverBounce’s email verification API version 4. To get up and running, make sure you have your API token on hand:

import neverbounce_sdk
api_key = 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
client = neverbounce_sdk.client(api_key=api_key,timeout=30)

And now you’re ready to use the client. You can check your account information:

info = client.account_info()
# info is {'billing_type': 'default', 'credits': 12345, ... }

You can verify single emails:

resp = client.single_check('[e-mail]')
resp['result']              # 'invalid'
resp['execution_time']      # 285

And you can create, query the status of, and control email verification bulk jobs:

emails = [
    {'email': '[e-mail]'},  # must have an 'email' key
    {'email': '[e-mail]',
    'best_when': 'cold'},             # may contain "metadata"
]
job = client.jobs_create(emails)

# all state-changing methods return a status object
resp = client.jobs_parse(job['id'], auto_start=False)
assert resp['status'] == 'success'

client.jobs_start(job['id'])
progress = client.jobs_status(job['id'])
print(progress)  # dict with keys 'job_status', 'started', 'percent_complete', etc

When creating a job, you may attach “metadata” in the form of additional keys to each object (python dict) included in the job input listing. Note that these additional keys will be broadcasted; i.e., every row of the result set for the job will contain an entry for every key - if the value of the key was not specified in the input, it will be the empty string in the job processing’s output.

All API operations return dictionaries with information about the execution of the operation or the results of the operation, whichever is more appropriate. The only exceptions are the client.search and client.results functions. The response generated by these API endpoints is paginated; therefore these functions return custom iterators that allow you to iterate across the API’s pagination:

all_my_jobs = client.jobs_search()
type(all_my_jobs)       # neverbounce_sdk.bulk.ResultIter
for job in all_my_jobs:
    # process job
    # this loop will make API calls behind the scenes, so be careful!
    if all_my_jobs.page > 10:
        break

The ResultIter will pull down pages behind the scenes, so be careful! A ResultIter will expose the raw API response as a data attribute, the current page number as page, and the total number of pages as total_pages, so you can use these attributes to implement finer-grained control over result iteration. Additionally, the methods raw_search and raw_results of the client object will return the raw API response (this is the same as the data attribute of the ResultIter object).

Behind the scenes the client uses requests, and if you would like to explicitly provide a requests.Session, you may do so:

from requests import Session
api_key = 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
session = Session()
client = neverbounce_sdk.client(api_key=api_key, session=session)

And all outgoing HTTP requests will be routed through the session object’s request method, taking advantage of requests.Session’s connection pooling. You may provide any custom object that provides a request interface with the same signature as that provided by requests.Session and a close method.

Finally, the client may be used a context manager. If a session is provided, it will be used for all connections in the with block; if not, a session will be created. Either way, a session associated with a client is always closed at the end of the context block.

with neverbounce_sdk.client() as client:
    client.api_key = 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

    # the client creates a session behind the scenes
    assert client.session is not None

    # do other stuff with the client

# and then removes it at the end of the block
assert client.session is None

See Also

Documentation for each function of the client object is available through Python’s built-in help function, e.g.:

>>> help(client.create)  # brings up a ton of information about the create
...                      # function's arguments and options

Many of the inputs and outputs of the client object’s functions map fairly closely to NeverBounce’s raw v4 API, reading through the official API docs<https://developers.neverbounce.com/v4.0/reference#account> will be valuable in conjunction with using the built-in online help.