Zero Bounce Python SDK

This SDK contains methods for interacting easily with ZeroBounce API. More information about ZeroBounce you can find in the official documentation.

Security

• Keep API keys on a trusted server. Do not embed them in mobile apps or browser JavaScript that untrusted users can inspect.
• Custom API base URLs (when supported) must use https://. Do not pass end-user-controlled hosts into those settings.
• Request URLs include api_key as a query parameter (ZeroBounce API contract). Do not log full request URLs or enable payload debug logging in production.

INSTALLATION

pip install zerobouncesdk

USAGE

Import the sdk in your file:

fromzerobouncesdkimportZeroBounce

Initialize the SDK with your API key. You can optionally specify a base URL to use a different API region or a custom endpoint:

Default: Uses the default ZeroBounce API endpoint

fromzerobouncesdkimportZeroBouncezero_bounce=ZeroBounce("<YOUR_API_KEY>")

Using predefined API regions: Use one of the available API regions

fromzerobouncesdkimportZeroBounce, ZBApiUrl# Use USA regionzero_bounce=ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_USA_URL)
# Use EU regionzero_bounce=ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_EU_URL)
# Use default region (explicit)zero_bounce=ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_DEFAULT_URL)

Using a custom URL string: Provide your own base URL

zero_bounce=ZeroBounce("<YOUR_API_KEY>", base_url="https://custom-api.example.com/v2")

Available API regions:

• ZBApiUrl.API_DEFAULT_URL - Default ZeroBounce API (https://api.zerobounce.net/v2/)
• ZBApiUrl.API_USA_URL - USA region API (https://api-us.zerobounce.net/v2/)
• ZBApiUrl.API_EU_URL - EU region API (https://api-eu.zerobounce.net/v2/)

Examples

Then you can use any of the SDK methods, for example:

• Check how many credits you have left on your account

fromzerobouncesdkimportZeroBouncezero_bounce=ZeroBounce("<YOUR_API_KEY>")
response=zero_bounce.get_credits()
print("ZeroBounce get_credits response: "+str(response))

• Check your API usage for a given period of time

fromdatetimeimportdatetimefromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
start_date=datetime(2019, 8, 1); # The start date of when you want to view API usageend_date=datetime(2019, 9, 1); # The end date of when you want to view API usagetry:
response=zero_bounce.get_api_usage(start_date, end_date)
print("ZeroBounce get_api_usage response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce get_api_usage error: "+str(e))

• Gather insights into your subscribers' overall email engagement

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
email="valid@example.com"; # Subscriber email addresstry:
response=zero_bounce.get_activity(email)
print("ZeroBounce get_activity response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce get_activity error: "+str(e))

• Find the correct email format when you provide a name and email domain or company name

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
# Option 1: Use find_email_format with domaindomain="example.com"# The email domain for which to find the email formatfirst_name="John"# The first name of the person whose email format is being searchedmiddle_name="Quill"# Optional: The middle name of the personlast_name="Doe"# Optional: The last name of the persontry:
response=zero_bounce.find_email_format(
first_name=first_name,
domain=domain,
middle_name=middle_name,
last_name=last_name
)
print("Email: "+str(response.email))
print("Email Confidence: "+str(response.email_confidence))
exceptZBExceptionase:
print("ZeroBounce find_email_format error: "+str(e))

# Option 2: Use find_email_format with company_namefromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
company_name="Acme Corp"# The company name for which to find the email formatfirst_name="Jane"# The first name of the persontry:
response=zero_bounce.find_email_format(
first_name=first_name,
company_name=company_name
)
print("Email: "+str(response.email))
print("Domain: "+str(response.domain))
print("Company: "+str(response.company_name))
exceptZBExceptionase:
print("ZeroBounce find_email_format error: "+str(e))

# Option 3: Use find_domain to discover email formats for a domainfromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
domain="example.com"# The email domain to analyzetry:
response=zero_bounce.find_domain(domain=domain)
print("Domain: "+str(response.domain))
print("Format: "+str(response.format))
print("Confidence: "+str(response.confidence))
print("Other formats: "+str(len(response.other_domain_formats)))
exceptZBExceptionase:
print("ZeroBounce find_domain error: "+str(e))

# Option 4: Use find_domain with company_namefromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
company_name="Acme Corp"# The company name to analyzetry:
response=zero_bounce.find_domain(company_name=company_name)
print("Domain: "+str(response.domain))
print("Company: "+str(response.company_name))
print("Format: "+str(response.format))
print("Confidence: "+str(response.confidence))
forfmtinresponse.other_domain_formats:
print(f" Alternative: {fmt.format} (confidence: {fmt.confidence})")
exceptZBExceptionase:
print("ZeroBounce find_domain error: "+str(e))

• Validate an email address

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
email="<EMAIL_ADDRESS>"# The email address you want to validateip_address="127.0.0.1"# The IP Address the email signed up from (Optional)try:
response=zero_bounce.validate(email, ip_address)
print("ZeroBounce validate response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce validate error: "+str(e))

• Validate a batch of up to 100 emails at a time

fromzerobouncesdkimportZeroBounce, ZBException, ZBValidateBatchElementzero_bounce=ZeroBounce("<YOUR_API_KEY>")
email_batch= [
ZBValidateBatchElement("valid@example.com", "127.0.0.1"),
ZBValidateBatchElement("invalid@example.com"),
] # The batch of emails you want to validatetry:
response=zero_bounce.validate_batch(email_batch)
print("ZeroBounce validate_batch response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce validate_batch error: "+str(e))

• The sendFile API allows user to send a file for bulk email validation

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
file_path='./email_file.csv'# The csv or txt fileemail_address_column=1# The index of "email" column in the file. Index starts at 1return_url="https://domain.com/called/after/processing/request"first_name_column=None# The index of "first name" column in the filelast_name_column=None# The index of "last name" column in the filegender_column=None# The index of "gender" column in the fileip_address_column=None# The index of "IP address" column in the filehas_header_row=False# If the first row from the submitted file is a header rowremove_duplicate=True# If you want the system to remove duplicate emailsallow_phase_2=True# Optional: sends allow_phase_2 (validation bulk only); omit or use None to skiptry:
response=zero_bounce.send_file(
file_path,
email_address_column,
return_url,
first_name_column,
last_name_column,
gender_column,
ip_address_column,
has_header_row,
remove_duplicate,
allow_phase_2,
)
print("ZeroBounce send_file response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce send_file error: "+str(e))

Bulk validation uses https://bulkapi.zerobounce.net/v2. See v2 send file, v2 file status, and v2 get file.

• Check the status of a file uploaded via sendFile method

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
file_id="<FILE_ID>"# The returned file ID when calling sendFile APItry:
response=zero_bounce.file_status(file_id)
# response.file_status, response.file_phase_2_status, response.error_reason (when present)print("ZeroBounce file_status response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce file_status error: "+str(e))

• The getfile API allows users to get the validation results file for the file been submitted using sendFile API

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
file_id="<FILE_ID>"# The returned file ID when calling sendFile APIlocal_download_path="./dwnld_file.csv"# The path where the file will be downloadedtry:
response=zero_bounce.get_file(file_id, local_download_path)
print("ZeroBounce get_file response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce get_file error: "+str(e))

Optional v2 get file query parameters use ZBGetFileOptions and ZBDownloadType (PHASE_1, PHASE_2, COMBINED). Set activity_data on the options object for validation get_file only; it is not sent for scoring_get_file.

fromzerobouncesdkimportZeroBounce, ZBException, ZBGetFileOptions, ZBDownloadTypezero_bounce=ZeroBounce("<YOUR_API_KEY>")
opts=ZBGetFileOptions(download_type=ZBDownloadType.COMBINED, activity_data=True)
response=zero_bounce.get_file(file_id, local_download_path, opts)

If the API returns a non-success HTTP status or a JSON error body (including some HTTP 200 responses with success: false), the client raises ZBApiException. To inspect a raw body string yourself, use ZeroBounce.get_file_json_indicates_error(body).

• Delete the file that was submitted using sendFile API. File can be deleted only when its status is Complete

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
file_id="<FILE_ID>"# The returned file ID when calling sendFile APItry:
response=zero_bounce.delete_file(file_id)
print("ZeroBounce delete_file response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce delete_file error: "+str(e))

AI Scoring API

• The scoringSendFile API allows user to send a file for bulk email scoring

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
file_path='./email_file.csv'# The csv or txt fileemail_address_column=1# The index of "email" column in the file. Index starts at 1return_url="https://domain.com/called/after/processing/request"has_header_row=False# If the first row from the submitted file is a header rowremove_duplicate=True# If you want the system to remove duplicate emailstry:
response=zero_bounce.scoring_send_file(
file_path,
email_address_column,
return_url,
has_header_row,
remove_duplicate,
)
print("ZeroBounce send_file response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce send_file error: "+str(e))

• Check the status of a file uploaded via scoringSendFile method

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
file_id="<FILE_ID>"# The returned file ID when calling scoringSendFile APItry:
response=zero_bounce.scoring_file_status(file_id)
print("ZeroBounce file_status response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce file_status error: "+str(e))

• The scoring scoringGetFile API allows users to get the validation results file for the file been submitted using scoring scoringSendFile API

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
file_id="<FILE_ID>"# The returned file ID when calling scoringSendFile APIlocal_download_path="./dwnld_file.csv"# The path where the file will be downloadedtry:
response=zero_bounce.scoring_get_file(file_id, local_download_path)
print("ZeroBounce get_file response: "+str(response))
# Optional third argument: ZBGetFileOptions with download_type only (activity_data is not used for scoring getfile)# response = zero_bounce.scoring_get_file(file_id, local_download_path, opts)exceptZBExceptionase:
print("ZeroBounce get_file error: "+str(e))

• Delete the file that was submitted using scoringSendFile API. File can be deleted only when its status is Complete

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
file_id="<FILE_ID>"# The returned file ID when calling scoringSendFile APItry:
response=zero_bounce.scoring_delete_file(file_id)
print("ZeroBounce delete_file response: "+str(response))
exceptZBExceptionase:
print("ZeroBounce delete_file error: "+str(e))

• (Deprecated) Identify the correct email format when you provide a name and email domain

⚠️ Deprecated: The guess_format method is deprecated and will be removed in future versions. Use find_email_format or find_domain instead (see examples above).

fromzerobouncesdkimportZeroBounce, ZBExceptionzero_bounce=ZeroBounce("<YOUR_API_KEY>")
domain="example.com"# The email domain for which to find the email formatfirst_name="John"# The first name of the person whose email format is being searchedmiddle_name="Quill"# The middle name of the person whose email format is being searchedlast_name="Doe"# The last name of the person whose email format is being searchedtry:
response=zero_bounce.guess_format(domain, first_name, middle_name, last_name)
print("ZeroBounce guess format response: "+response)
exceptZBExceptionase:
print("ZeroBounce guess format error: "+str(e))

DEVELOPMENT

Local setup

python -m venv venv # python 3.12+source venv/bin/activate
pip install -e .

Run tests with Docker

From the sdk-docs/ folder in the SDKs monorepo:

cd sdk-docs
docker compose build python
docker compose run --rm python

Or build and run this SDK’s image from this directory:

docker build -t zb-python-sdk .
docker run --rm zb-python-sdk

Run tests (local)

python -m tests -v
# output:
python -m tests -v test_api_regions (tests.zero_bounce_integration_test.ZeroBounceIntegrationTestCase.test_api_regions)
Test that different API regions work. ... skipped 'ZEROBOUNCE_API_KEY environment variable not set'
test_error_handling_invalid_key (tests.zero_bounce_integration_test.ZeroBounceIntegrationTestCase.test_error_handling_invalid_key)
Test error handling with invalid API key. ... skipped 'ZEROBOUNCE_API_KEY environment variable not set'
test_find_domain_with_domain (tests.zero_bounce_integration_test.ZeroBounceIntegrationTestCase.test_find_domain_with_domain)
Test find_domain with domain parameter. ... skipped 'ZEROBOUNCE_API_KEY environment variable not set'
----------------------------------------------------------------------
Ran 4 tests in 0.015s
OK (skipped=10) # integration tests are skipped if no api key is present

# to run integration tests export api key into the environment (valid api key required)export ZEROBOUNCE_API_KEY=<apikey>&& python -m tests -v
# output:
test_api_regions (tests.zero_bounce_integration_test.ZeroBounceIntegrationTestCase.test_api_regions)
Test that different API regions work. ... ok
test_error_handling_invalid_key (tests.zero_bounce_integration_test.ZeroBounceIntegrationTestCase.test_error_handling_invalid_key)
Test error handling with invalid API key. ... ok
----------------------------------------------------------------------
Ran 4 tests in 1.1s
OK

Publish

1. Bump version in pyproject.toml, commit, tag (vX.Y.Z), push tag.
2. Actions → Publish → Run workflow with that tag.

Registry: zerobouncesdk on PyPI