ZeroBounce Python SDK

2.2.0 · active · verified Thu Apr 16

The `zerobouncesdk` is a Python library that provides an easy-to-use interface for interacting with the ZeroBounce email verification API. It allows developers to validate email addresses, check API usage, retrieve credit balance, and perform bulk email validation. The current version is 2.2.0, and it features a regular release cadence with frequent updates and occasional major versions that introduce new features and improvements.

Common errors

```
ModuleNotFoundError: No module named 'zerobouncesdk'
```
cause The `zerobouncesdk` package is not installed in your Python environment.

fix Run `pip install zerobouncesdk` to install the library.
```
ZeroBounce get_credits response: {'success': False, 'message': 'Invalid API Key'}
```
cause The API key provided to the `ZeroBounce` constructor is incorrect, expired, or revoked.

fix Verify your ZeroBounce API key in your ZeroBounce account dashboard and ensure it is correctly passed to the `ZeroBounce` constructor. Check for typos or leading/trailing spaces.
```
Error getting credits: Missing key request attributes
```
cause While less common for `get_credits`, this general API error indicates a required parameter (e.g., `email` for validation) was omitted or malformed in the API call.

fix Review the specific method's documentation (e.g., `validate(email, ip_address)`) to ensure all required arguments are provided and correctly formatted.

Warnings

breaking Upgrading from `zerobouncesdk` v1.x to v2.x introduces breaking changes. While an explicit migration guide for the Python SDK isn't extensively documented, major version bumps often imply changes to method signatures, response object structures, or added mandatory parameters, as seen with new status fields and updated domain finding capabilities in v2.0.0.
Fix: Review the official ZeroBounce API documentation and the SDK's changelog for `v2.0.0` to identify specific changes. Test your integration thoroughly after upgrading to ensure compatibility with new API responses and method behaviors.
gotcha Directly embedding your ZeroBounce API key in your code is a security risk. It can lead to unauthorized access to your account and API usage.
Fix: Always store your API key securely, preferably using environment variables (e.g., `os.environ.get('ZEROBOUNCE_API_KEY')`), or a secure configuration management system. Avoid hardcoding credentials.
gotcha The ZeroBounce API has rate limits. Making too many requests in a short period without proper handling can lead to `ZBException` or API-level errors.
Fix: Implement robust error handling, including `try-except ZBException` blocks, and check the `success` field and `message` or `errors` fields in API responses. Consider implementing rate limiting or exponential backoff for bulk operations.

Install

pip install zerobouncesdk Install latest version

Imports

ZeroBounce
```
from zerobouncesdk import ZeroBounce
```
ZBApiUrl
```
from zerobouncesdk import ZBApiUrl
```
Used for specifying different ZeroBounce API regions (e.g., USA, EU).
ZBException
```
from zerobouncesdk import ZBException
```
Base exception class for ZeroBounce API errors.

Quickstart

This quickstart demonstrates how to initialize the ZeroBounce SDK with your API key, check your remaining credits, and perform a single email validation. It uses environment variables for secure API key handling and includes basic error checking.

import os
from zerobouncesdk import ZeroBounce, ZBException

API_KEY = os.environ.get('ZEROBOUNCE_API_KEY', 'YOUR_API_KEY')

if API_KEY == 'YOUR_API_KEY':
    print("Please set the ZEROBOUNCE_API_KEY environment variable or replace 'YOUR_API_KEY'.")
else:
    try:
        zero_bounce = ZeroBounce(API_KEY)
        # Get credit balance
        response = zero_bounce.get_credits()
        if response.get('success'):
            print(f"Remaining Credits: {response.get('credits')}")
        else:
            print(f"Error getting credits: {response.get('message')}")
            if response.get('errors'):
                for error in response.get('errors'):
                    print(f" - {error.get('field')}: {error.get('message')}")

        # Example: Validate a single email (replace with a real email for testing)
        email_to_validate = 'test@example.com'
        ip_address = '127.0.0.1'
        validation_response = zero_bounce.validate(email_to_validate, ip_address)
        if validation_response.get('success'):
            print(f"Validation for {email_to_validate}: Status = {validation_response.get('status')}, Sub Status = {validation_response.get('sub_status')}")
        else:
            print(f"Error validating {email_to_validate}: {validation_response.get('message')}")

    except ZBException as e:
        print(f"An SDK exception occurred: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →