ZeroBounce Python SDK

https://github.com/zerobounce/zero-bounce-python-sdk-setup
Admin
ZeroBounce Python SDK provides easy-to-use methods for email validation, verification, and scoring...
Tokens:24,313
Snippets:163
Trust Score:7.5
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Local Setup: Create Virtual Environment and Install SDK

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/README.md

Commands to set up a local Python development environment using a virtual environment and install the SDK in editable mode.

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

--------------------------------

### Install ZeroBounce Python SDK

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Install the ZeroBounce Python SDK using pip. This is the first step to integrate ZeroBounce services into your Python application.

```bash
pip install zerobouncesdk
```

--------------------------------

### Import Zero Bounce SDK

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/README.md

Import the ZeroBounce class from the zerobouncesdk package to start using its functionalities.

```python
from zerobouncesdk import ZeroBounce
```

--------------------------------

### Get Account Credits

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Check the remaining credits on your ZeroBounce account.

```python
from zerobouncesdk import ZeroBounce

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

--------------------------------

### Get Activity

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Gather insights into your subscribers' overall email engagement.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

email = "valid@example.com"

try:
    response = zero_bounce.get_activity(email)
    print("ZeroBounce get_activity response: " + str(response))
except ZBException as e:
    print("ZeroBounce get_activity error: " + str(e))
```

--------------------------------

### Get File with Options

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

This snippet demonstrates how to retrieve a processed file using the `get_file` method with custom options for download type and activity data. It also explains how the SDK handles API errors by raising `ZBApiException`.

```APIDOC
## get_file with options

### Description
Retrieves a processed file with specified options. Handles API errors by raising `ZBApiException`.

### Method
`zero_bounce.get_file(file_id, local_download_path, opts)`

### Parameters
- **file_id** (string) - Required - The ID of the file to retrieve.
- **local_download_path** (string) - Required - The local path where the file will be downloaded.
- **opts** (ZBGetFileOptions) - Optional - An object containing options like `download_type` and `activity_data`.

### Request Example
```python
from zerobouncesdk import ZeroBounce, ZBException, ZBGetFileOptions, ZBDownloadType

zero_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)
```

### Error Handling
If the API returns a non-success HTTP status or a JSON error body, `ZBApiException` is raised. Use `ZeroBounce.get_file_json_indicates_error(body)` to check raw body strings.
```

--------------------------------

### Get ZeroBounce API Usage

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Fetch your API usage statistics for a specified date range. This requires importing `datetime` and handling potential `ZBException` errors.

```python
from datetime import datetime
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

start_date = datetime(2019, 8, 1);  # The start date of when you want to view API usage
end_date = datetime(2019, 9, 1);    # The end date of when you want to view API usage

try:
    response = zero_bounce.get_api_usage(start_date, end_date)
    print("ZeroBounce get_api_usage response: " + str(response))
except ZBException as e:
    print("ZeroBounce get_api_usage error: " + str(e))
```

--------------------------------

### Get Bulk Validation Results File using ZeroBounce SDK

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Download the validation results file for a bulk job submitted via the `sendFile` API. You need the file ID obtained from the `sendFile` call. Specify a local path for the downloaded file.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

file_id="<FILE_ID>"                         # The returned file ID when calling sendFile API
local_download_path = "./dwnld_file.csv"    # The path where the file will be downloaded

try:
    response = zero_bounce.get_file(file_id, local_download_path)
    print("ZeroBounce get_file response: " + str(response))
except ZBException as e:
    print("ZeroBounce get_file error: " + str(e))
```

--------------------------------

### Get API Usage

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/README.md

Check your API usage for a given period of time.

```APIDOC
## Get API Usage

### Description
Retrieves your API usage statistics for a specified date range.

### Method
`get_api_usage(start_date: datetime, end_date: datetime)`

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **start_date** (datetime) - Required - The start date of the period for which to view API usage.
- **end_date** (datetime) - Required - The end date of the period for which to view API usage.

### Request Example
```python
from datetime import datetime
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")
start_date = datetime(2019, 8, 1)
end_date = datetime(2019, 9, 1)

try:
    response = zero_bounce.get_api_usage(start_date, end_date)
    print("ZeroBounce get_api_usage response: " + str(response))
except ZBException as e:
    print("ZeroBounce get_api_usage error: " + str(e))
```

### Response
#### Success Response
- **usage_data** (dict) - A dictionary containing API usage statistics for the specified period.

#### Response Example
```json
{
  "usage_data": {
    "total_api_calls": 500,
    "total_validations": 450,
    "total_credits_consumed": 50
  }
}
```
```

--------------------------------

### Delete File

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

This code example shows how to delete a file that was previously submitted using the `sendFile` API. Deletion is only possible when the file's status is 'Complete'. Error handling for `ZBException` is included.

```APIDOC
## delete_file

### Description
Deletes a processed file. This operation is only available when the file status is 'Complete'.

### Method
`zero_bounce.delete_file(file_id)`

### Parameters
- **file_id** (string) - Required - The ID of the file to delete.

### Request Example
```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")
file_id="<FILE_ID>"

try:
    response = zero_bounce.delete_file(file_id)
    print("ZeroBounce delete_file response: " + str(response))
except ZBException as e:
    print("ZeroBounce delete_file error: " + str(e))
```

### Response
- **response** (string) - The response from the delete operation.

### Error Handling
Catches `ZBException` for potential errors during the deletion process.
```

--------------------------------

### Get File Results

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

This snippet demonstrates how to retrieve the validation results file for a submitted file using the `get_file` method.

```APIDOC
## get_file

### Description
Allows users to get the validation results file for a file submitted using the `sendFile` API.

### Method
`get_file(file_id: str, local_download_path: str)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")
file_id="<FILE_ID>"
local_download_path = "./dwnld_file.csv"
response = zero_bounce.get_file(file_id, local_download_path)
print("ZeroBounce get_file response: " + str(response))
```

### Response
#### Success Response (200)
Returns a confirmation message upon successful download of the results file.

#### Response Example
```json
{
  "message": "File downloaded successfully to ./dwnld_file.csv"
}
```

ERROR HANDLING:
- `ZBException`: Raised for any errors during the API call.
```

--------------------------------

### Get API Usage

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Retrieve your API usage statistics for a specified date range.

```python
from datetime import datetime
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

start_date = datetime(2019, 8, 1)
end_date = datetime(2019, 9, 1)

try:
    response = zero_bounce.get_api_usage(start_date, end_date)
    print("ZeroBounce get_api_usage response: " + str(response))
except ZBException as e:
    print("ZeroBounce get_api_usage error: " + str(e))
```

--------------------------------

### Get ZeroBounce Account Credits

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Retrieve the remaining credits on your ZeroBounce account. Ensure the SDK is initialized with your API key before calling this method.

```python
from zerobouncesdk import ZeroBounce

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

response = zero_bounce.get_credits()
print("ZeroBounce get_credits response: " + str(response))
```

--------------------------------

### Get AI Scoring Results File

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Download the validation results file for a submitted scoring job using the file ID. Specify the local path where the file should be saved.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

file_id="<FILE_ID>"                         # The returned file ID when calling scoringSendFile API
local_download_path = "./dwnld_file.csv"    # The path where the file will be downloaded

try:
    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)
except ZBException as e:
    print("ZeroBounce get_file error: " + str(e))
```

--------------------------------

### Retrieve API Usage Statistics

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Get API usage statistics between specified dates using `get_api_usage`. Catches `ZBApiException` for error handling.

```python
from datetime import datetime
from zerobouncesdk import ZeroBounce, ZBApiException

zero_bounce = ZeroBounce("your_api_key_here")

start_date = datetime(2024, 1, 1)
end_date = datetime(2024, 6, 30)

try:
    response = zero_bounce.get_api_usage(start_date, end_date)
    print(f"Total requests: {response.total}")
    print(f"Valid emails: {response.valid}")
    print(f"Invalid emails: {response.invalid}")
    print(f"Usage: {response}")
except ZBApiException as e:
    print(f"Error: {e}")
```

--------------------------------

### Get Email Engagement Activity

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Fetch subscriber email engagement metrics like opens and clicks for a given email address using `get_activity`. Includes error handling for `ZBApiException`.

```python
from zerobouncesdk import ZeroBounce, ZBApiException

zero_bounce = ZeroBounce("your_api_key_here")

try:
    response = zero_bounce.get_activity("subscriber@example.com")
    print(f"Activity score: {response.activity_score}")
    print(f"Opens: {response.opens}")
    print(f"Clicks: {response.clicks}")
    print(f"Response: {response}")
except ZBApiException as e:
    print(f"Error fetching activity: {e}")
```

--------------------------------

### Get Validation Results File

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/README.md

Retrieve the validation results file for a submitted file using the `get_file` method. This allows you to download the processed results to a specified local path.

```APIDOC
## get_file

### Description
Retrieves the validation results file for a submitted file.

### Method
`get_file(file_id: str, local_download_path: str)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **file_id** (string) - Required - The unique file ID returned when calling the `sendFile` API.
- **local_download_path** (string) - Required - The local path where the results file will be downloaded.

### Request Example
```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")
file_id="<FILE_ID>"
local_download_path = "./dwnld_file.csv"
response = zero_bounce.get_file(file_id, local_download_path)
print(response)
```

### Response
#### Success Response (200)
- The response indicates the success of the file download operation. The actual file content is saved to `local_download_path`.

#### Response Example
```json
{
  "message": "File downloaded successfully to ./dwnld_file.csv"
}
```
```

--------------------------------

### Import and Initialize ZeroBounce SDK (Default)

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Import the ZeroBounce SDK and initialize it with your API key. This uses the default ZeroBounce API endpoint.

```python
from zerobouncesdk import ZeroBounce

zero_bounce = ZeroBounce("<YOUR_API_KEY>")
```

--------------------------------

### SDK Initialization

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Initialize the ZeroBounce SDK with your API key. You can use the default API endpoint, predefined regions, or a custom URL.

```python
from zerobouncesdk import ZeroBounce

# Default initialization
zero_bounce = ZeroBounce("<YOUR_API_KEY>")

# Using predefined API regions
from zerobouncesdk import ZBApiUrl

# Use USA region
zero_bounce_usa = ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_USA_URL)

# Use EU region
zero_bounce_eu = ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_EU_URL)

# Use default region (explicit)
zero_bounce_default = ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_DEFAULT_URL)

# Using a custom URL string
zero_bounce_custom = ZeroBounce("<YOUR_API_KEY>", base_url="https://custom-api.example.com/v2")
```

--------------------------------

### Run Tests with Docker

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/README.md

Instructions for building and running tests for the Python SDK using Docker Compose, either from the parent repository root or from the SDK's directory.

```bash
docker compose build python
docker compose run --rm python
```

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

--------------------------------

### Initialization

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Initialize the ZeroBounce client with your API key and optional region or custom base URL. The client supports different regional endpoints and custom timeouts.

```APIDOC
## Initialization

**Initialize the ZeroBounce client** with your API key and optional region or custom base URL.

```python
from zerobouncesdk import ZeroBounce, ZBApiUrl
from datetime import timedelta

# Default endpoint
zero_bounce = ZeroBounce("your_api_key_here")

# USA region
zero_bounce = ZeroBounce("your_api_key_here", base_url=ZBApiUrl.API_USA_URL)

# EU region
zero_bounce = ZeroBounce("your_api_key_here", base_url=ZBApiUrl.API_EU_URL)

# Custom endpoint with optional request timeout
zero_bounce = ZeroBounce(
    "your_api_key_here",
    base_url="https://custom-api.example.com/v2",
    timeout=timedelta(seconds=30)
)
```

Available `ZBApiUrl` values:
- `ZBApiUrl.API_DEFAULT_URL` → `https://api.zerobounce.net/v2/`
- `ZBApiUrl.API_USA_URL` → `https://api-us.zerobounce.net/v2/`
- `ZBApiUrl.API_EU_URL` → `https://api-eu.zerobounce.net/v2/`
```

--------------------------------

### Get Subscriber Activity

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/README.md

Gather insights into your subscribers' overall email engagement.

```APIDOC
## Get Subscriber Activity

### Description
Provides insights into a subscriber's email engagement patterns.

### Method
`get_activity(email: str)`

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **email** (str) - Required - The subscriber's email address.

### Request Example
```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")
email = "valid@example.com"

try:
    response = zero_bounce.get_activity(email)
    print("ZeroBounce get_activity response: " + str(response))
except ZBException as e:
    print("ZeroBounce get_activity error: " + str(e))
```

### Response
#### Success Response
- **engagement_score** (int) - The engagement score of the subscriber.
- **last_activity** (str) - The date of the subscriber's last activity.

#### Response Example
```json
{
  "engagement_score": 85,
  "last_activity": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Run Tests Locally

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/README.md

Command to execute the SDK's tests directly on the local machine.

```bash
python -m tests -v
```

--------------------------------

### Initialize ZeroBounce SDK with Predefined API Regions

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Initialize the ZeroBounce SDK specifying a base URL for different API regions like USA or EU. This allows you to route requests to specific data centers.

```python
from zerobouncesdk import ZeroBounce, ZBApiUrl

# Use USA region
zero_bounce = ZeroBounce("<YOUR_API_KEY>", base_url=ZBApiUrl.API_USA_URL)

# Use EU region
zero_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)
```

--------------------------------

### Initialize ZeroBounce Client

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Initialize the ZeroBounce client with your API key. Supports default, USA, and EU regions, or a custom endpoint with a configurable timeout.

```python
from zerobouncesdk import ZeroBounce, ZBApiUrl
from datetime import timedelta

# Default endpoint
zero_bounce = ZeroBounce("your_api_key_here")

# USA region
zero_bounce = ZeroBounce("your_api_key_here", base_url=ZBApiUrl.API_USA_URL)

# EU region
zero_bounce = ZeroBounce("your_api_key_here", base_url=ZBApiUrl.API_EU_URL)

# Custom endpoint with optional request timeout
zero_bounce = ZeroBounce(
    "your_api_key_here",
    base_url="https://custom-api.example.com/v2",
    timeout=timedelta(seconds=30)
)
```

--------------------------------

### Run Integration Tests with API Key

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/README.md

To run integration tests, export your valid API key to the ZEROBOUNCE_API_KEY environment variable before executing the tests. This ensures all tests, including integration-specific ones, can pass.

```bash
# to run integration tests export api key into the environment (valid api key required)
export ZEROBOUNCE_API_KEY=<apikey> && python -m tests -v
```

--------------------------------

### Initialize ZeroBounce SDK with Custom URL

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Initialize the ZeroBounce SDK with a custom API endpoint URL. This is useful for private deployments or specific regional endpoints not covered by predefined options.

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

--------------------------------

### get_activity

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Get Email Engagement Activity. Returns subscriber email engagement metrics (opens, clicks, forwards, etc.) for a given email address as a `ZBGetActivityResponse`.

```APIDOC
## `get_activity` — Get Email Engagement Activity

Returns subscriber email engagement metrics (opens, clicks, forwards, etc.) for a given email address as a `ZBGetActivityResponse`.

```python
from zerobouncesdk import ZeroBounce, ZBApiException

zero_bounce = ZeroBounce("your_api_key_here")

try:
    response = zero_bounce.get_activity("subscriber@example.com")
    print(f"Activity score: {response.activity_score}")
    print(f"Opens: {response.opens}")
    print(f"Clicks: {response.clicks}")
    print(f"Response: {response}")
except ZBApiException as e:
    print(f"Error fetching activity: {e}")
```
```

--------------------------------

### Download Processed File with Options

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Use `get_file` to download processed files. Specify download type and activity data options. The client raises `ZBApiException` on API errors.

```python
from zerobouncesdk import ZeroBounce, ZBException, ZBGetFileOptions, ZBDownloadType

zero_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)
```

--------------------------------

### Get Email Activity Insights

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Gather insights into a subscriber's email engagement. This method requires the subscriber's email address and handles potential `ZBException` errors.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

email = "valid@example.com";    # Subscriber email address

try:
    response = zero_bounce.get_activity(email)
    print("ZeroBounce get_activity response: " + str(response))
except ZBException as e:
    print("ZeroBounce get_activity error: " + str(e))
```

--------------------------------

### Create a New Branch

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/CONTRIBUTING.md

Before making changes, fork the repository and create a new branch from 'main' to isolate your work.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### ZeroBounce SDK Exception Handling

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Illustrates how to handle different types of exceptions from the ZeroBounce SDK, including general ZBException, API-specific ZBApiException, and client-side ZBClientException. This ensures robust error management for SDK operations.

```python
from zerobouncesdk import ZeroBounce, ZBException, ZBApiException, ZBClientException

zero_bounce = ZeroBounce("your_api_key_here")

try:
    response = zero_bounce.validate("test@example.com")
except ZBClientException as e:
    # Raised for invalid input (e.g., empty api_key, empty file_path, conflicting params)
    print(f"Client error: {e}")
except ZBApiException as e:
    # Raised for API-level errors (bad key, quota exceeded, invalid response, HTTP errors)
    print(f"API error: {e}")
except ZBException as e:
    # Base class — catches both of the above
    print(f"ZeroBounce error: {e}")
```

--------------------------------

### Submit a File Stream for Bulk Validation with ZeroBounce SDK

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Use this to send a bulk validation file directly from a binary stream, such as an `io.BytesIO` object, without needing to save it to disk first. Requires specifying the stream, file name, and email column.

```python
import io
from zerobouncesdk import ZeroBounce, ZBApiException

zero_bounce = ZeroBounce("your_api_key_here")

csv_content = b"email,first_name\nvalid@example.com,John\nbad@invalid.xyz,Jane\n"
file_stream = io.BytesIO(csv_content)

try:
    response = zero_bounce.send_file_stream(
        file_stream=file_stream,
        file_name="emails.csv",
        email_address_column=1,
        has_header_row=True,
        remove_duplicate=True,
    )
    print(f"File ID: {response.file_id}")
except ZBApiException as e:
    print(f"Error: {e}")
```

--------------------------------

### Submit File Stream for Bulk AI Scoring with Python SDK

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Submits a bulk AI scoring file directly from a binary stream without needing to write it to disk first. Requires the file stream, a file name, the email address column, and header row information. Handles API errors during submission.

```python
import io
from zerobouncesdk import ZeroBounce, ZBApiException

zero_bounce = ZeroBounce("your_api_key_here")

csv_content = b"email\ntest@example.com\nuser@domain.org\n"
file_stream = io.BytesIO(csv_content)

try:
    response = zero_bounce.scoring_send_file_stream(
        file_stream=file_stream,
        file_name="emails.csv",
        email_address_column=1,
        has_header_row=True,
    )
    print(f"Scoring file ID: {response.file_id}")
except ZBApiException as e:
    print(f"Error: {e}")
```

--------------------------------

### Submit a CSV File for Bulk Email Validation with ZeroBounce SDK

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Use this to upload a CSV or TXT file for asynchronous bulk email validation. Specify the file path, the column containing email addresses, and optionally other columns like first name, last name, and IP address. A return URL for webhooks is required.

```python
from zerobouncesdk import ZeroBounce, ZBApiException

zero_bounce = ZeroBounce("your_api_key_here")

try:
    response = zero_bounce.send_file(
        file_path="./emails.csv",
        email_address_column=1,          # Column index (1-based) containing emails
        return_url="https://myapp.com/webhook/zerobounce",
        first_name_column=2,             # Optional: column index of first name
        last_name_column=3,              # Optional: column index of last name
        ip_address_column=4,             # Optional: column index of sign-up IP
        has_header_row=True,
        remove_duplicate=True,
        allow_phase_2=True,              # Enable phase 2 deep validation
    )
    print(f"File submitted. File ID: {response.file_id}")
    # File ID: aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff
except ZBApiException as e:
    print(f"Error submitting file: {e}")
```

--------------------------------

### Exception Hierarchy

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Details the exception hierarchy for the ZeroBounce SDK, including `ZBException`, `ZBApiException`, and `ZBClientException`.

```APIDOC
## Exception Hierarchy

### Description
All SDK errors derive from `ZBException`. Use `ZBApiException` for server-side API errors and `ZBClientException` for invalid client-side input (empty parameters, conflicting arguments, etc.).

### Usage
```python
from zerobouncesdk import ZeroBounce, ZBException, ZBApiException, ZBClientException

zero_bounce = ZeroBounce("your_api_key_here")

try:
    response = zero_bounce.validate("test@example.com")
except ZBClientException as e:
    # Raised for invalid input (e.g., empty api_key, empty file_path, conflicting params)
    print(f"Client error: {e}")
except ZBApiException as e:
    # Raised for API-level errors (bad key, quota exceeded, invalid response, HTTP errors)
    print(f"API error: {e}")
except ZBException as e:
    # Base class — catches both of the above
    print(f"ZeroBounce error: {e}")
```

### Exception Types
- **ZBException**: The base class for all ZeroBounce SDK exceptions.
- **ZBApiException**: Raised for server-side API errors.
- **ZBClientException**: Raised for invalid client-side input.
```

--------------------------------

### Find Email Format using Domain and Name

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Find the correct email format for a given domain and person's name (first, middle, last). This method helps in constructing valid email addresses.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

# Option 1: Use find_email_format with domain
domain = "example.com"  # The email domain for which to find the email format
first_name = "John"      # The first name of the person whose email format is being searched
middle_name = "Quill"    # Optional: The middle name of the person
last_name = "Doe"        # Optional: The last name of the person

try:
    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))
except ZBException as e:
    print("ZeroBounce find_email_format error: " + str(e))
```

--------------------------------

### Send File for Bulk Email Validation using ZeroBounce SDK

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Submit a CSV or TXT file for bulk email validation. Specify column indices for email addresses and other optional data, and configure header row presence and duplicate removal. A return URL is required for notifications.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

file_path = './email_file.csv'  # The csv or txt file
email_address_column = 1        # The index of "email" column in the file. Index starts at 1
return_url = "https://domain.com/called/after/processing/request"
first_name_column = None        # The index of "first name" column in the file
last_name_column = None         # The index of "last name" column in the file
gender_column = None            # The index of "gender" column in the file
ip_address_column = None        # The index of "IP address" column in the file
has_header_row = False          # If the first row from the submitted file is a header row
remove_duplicate = True         # If you want the system to remove duplicate emails
allow_phase_2 = True            # Optional: sends allow_phase_2 (validation bulk only); omit or use None to skip

try:
    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))
except ZBException as e:
    print("ZeroBounce send_file error: " + str(e))
```

--------------------------------

### Download Bulk Validation Results with Python SDK

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Downloads completed validation results as a CSV file. Supports options for specifying download type (phase 1, phase 2, or combined) and including activity data. Includes a utility to check if a raw response body indicates an error.

```python
from zerobouncesdk import ZeroBounce, ZBApiException, ZBGetFileOptions, ZBDownloadType

zero_bounce = ZeroBounce("your_api_key_here")

file_id = "aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff"

try:
    # Basic download
    response = zero_bounce.get_file(file_id, "./results.csv")
    print(f"Downloaded to: {response.local_file_path}")

    # With options: download combined phase 1 + phase 2, include activity data
    opts = ZBGetFileOptions(download_type=ZBDownloadType.COMBINED, activity_data=True)
    response = zero_bounce.get_file(file_id, "./results_combined.csv", opts)
    print(f"Downloaded to: {response.local_file_path}")
except ZBApiException as e:
    print(f"Download error: {e}")

# Manually check if a raw response body is a JSON error (useful for custom handling)
raw_body = '{"success": false, "message": "File not found"}'
is_error = ZeroBounce.get_file_json_indicates_error(raw_body)
print(f"Is error: {is_error}")  # Is error: True
```

--------------------------------

### Download and Delete Scoring Results

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Demonstrates how to download scoring results using a file ID and options, and how to delete a scoring file once its status is 'Complete'. Handles potential API exceptions during these operations.

```python
from zerobouncesdk import ZBGetFileOptions, ZBDownloadType, ZBApiException

# Download scoring results (activity_data is not sent for scoring getfile)
try:
    opts = ZBGetFileOptions(download_type=ZBDownloadType.PHASE_1)
    response = zero_bounce.scoring_get_file(file_id, "./scoring_results.csv", opts)
    print(f"Results saved to: {response.local_file_path}")
except ZBApiException as e:
    print(f"Download error: {e}")

# Delete scoring file (only when status is Complete)
try:
    delete_resp = zero_bounce.scoring_delete_file(file_id)
    print(f"Deleted: {delete_resp.success}")
except ZBApiException as e:
    print(f"Delete error: {e}")
```

--------------------------------

### Submit Bulk AI Scoring File from Stream

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Submits a bulk AI scoring file from a binary stream without writing to disk first.

```APIDOC
## AI Scoring API — `scoring_send_file_stream`

Submits a bulk AI scoring file from a binary stream without writing to disk first.

```python
import io
from zerobouncesdk import ZeroBounce, ZBApiException

zero_bounce = ZeroBounce("your_api_key_here")

csv_content = b"email\ntest@example.com\nuser@domain.org\n"
file_stream = io.BytesIO(csv_content)

try:
    response = zero_bounce.scoring_send_file_stream(
        file_stream=file_stream,
        file_name="emails.csv",
        email_address_column=1,
        has_header_row=True,
    )
    print(f"Scoring file ID: {response.file_id}")
except ZBApiException as e:
    print(f"Error: {e}")
```
```

--------------------------------

### Find Domain by Company Name using ZeroBounce SDK

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Use this function to find a company's domain name when only the company name is known. It returns domain details and alternative formats if available. Ensure you have your API key configured.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

company_name = "Acme Corp"  # The company name to analyze

try:
    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))
    for fmt in response.other_domain_formats:
        print(f"  Alternative: {fmt.format} (confidence: {fmt.confidence})")
except ZBException as e:
    print("ZeroBounce find_domain error: " + str(e))
```

--------------------------------

### Submit File for Bulk AI Scoring with Python SDK

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Submits a CSV or TXT file for bulk AI-based email quality scoring. Requires specifying the file path, the column containing email addresses, and optionally a return URL, header row presence, and duplicate removal. Handles API errors during submission.

```python
from zerobouncesdk import ZeroBounce, ZBApiException

zero_bounce = ZeroBounce("your_api_key_here")

try:
    response = zero_bounce.scoring_send_file(
        file_path="./emails.csv",
        email_address_column=1,
        return_url="https://myapp.com/webhook/scoring",
        has_header_row=True,
        remove_duplicate=True,
    )
    print(f"Scoring file submitted. File ID: {response.file_id}")
except ZBApiException as e:
    print(f"Error: {e}")
```

--------------------------------

### Send File for Bulk Email Validation with ZeroBounce SDK

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/README.md

Use the `send_file` API to submit a file (CSV or TXT) for bulk email validation. Configure column mappings, header rows, and duplicate removal.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

file_path = './email_file.csv'  # The csv or txt file
email_address_column = 1        # The index of "email" column in the file. Index starts at 1

return_url = "https://domain.com/called/after/processing/request"

first_name_column = None        # The index of "first name" column in the file
last_name_column = None         # The index of "last name" column in the file
gender_column = None            # The index of "gender" column in the file
ip_address_column = None        # The index of "IP address" column in the file
has_header_row = False          # If the first row from the submitted file is a header row
remove_duplicate = True         # If you want the system to remove duplicate emails
allow_phase_2 = True            # Optional: sends allow_phase_2 (validation bulk only); omit or use None to skip

try:
    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))
except ZBException as e:
    print("ZeroBounce send_file error: " + str(e))
```

--------------------------------

### Find Email Format using Company Name

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Find the correct email format for a given company name and first name. This is an alternative to using the domain when company information is available.

```python
# Option 2: Use find_email_format with company_name
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

company_name = "Acme Corp"  # The company name for which to find the email format
first_name = "Jane"          # The first name of the person

try:
    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))
except ZBException as e:
    print("ZeroBounce find_email_format error: " + str(e))
```

--------------------------------

### Discover Email Formats for a Domain

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Analyze a domain to discover common email formats used within it. This method provides insights into potential email structures for a given domain.

```python
# Option 3: Use find_domain to discover email formats for a domain
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

domain = "example.com"  # The email domain to analyze

try:
    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)))
except ZBException as e:
    print("ZeroBounce find_domain error: " + str(e))
```

--------------------------------

### Find Email Format (by company name)

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Find the correct email format when you provide a name and company name. This method uses the first name and company name to suggest an email format.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

company_name = "Acme Corp"
first_name = "Jane"

try:
    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))
except ZBException as e:
    print("ZeroBounce find_email_format error: " + str(e))
```

--------------------------------

### Check Status of Bulk Validation File with ZeroBounce SDK

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Retrieve the processing status of a file previously submitted for bulk validation using the `sendFile` method. This function requires the file ID returned by `sendFile`. It provides status for both phase 1 and phase 2 processing.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

file_id = "<FILE_ID>"       # The returned file ID when calling sendFile API

try:
    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))
except ZBException as e:
    print("ZeroBounce file_status error: " + str(e))
```

--------------------------------

### `send_file` — Submit a CSV File for Bulk Email Validation

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Uploads a CSV or TXT file containing email addresses for asynchronous bulk validation. It returns a `ZBSendFileResponse` which includes a `file_id` for tracking the validation process.

```APIDOC
## `send_file` — Submit a CSV File for Bulk Email Validation

Uploads a CSV or TXT file containing email addresses for asynchronous bulk validation. Returns a `ZBSendFileResponse` with a `file_id` used to track and retrieve results.

```python
from zerobouncesdk import ZeroBounce, ZBApiException

zero_bounce = ZeroBounce("your_api_key_here")

try:
    response = zero_bounce.send_file(
        file_path="./emails.csv",
        email_address_column=1,          # Column index (1-based) containing emails
        return_url="https://myapp.com/webhook/zerobounce",
        first_name_column=2,             # Optional: column index of first name
        last_name_column=3,              # Optional: column index of last name
        ip_address_column=4,             # Optional: column index of sign-up IP
        has_header_row=True,
        remove_duplicate=True,
        allow_phase_2=True,              # Enable phase 2 deep validation
    )
    print(f"File submitted. File ID: {response.file_id}")
    # File ID: aaaaaaaa-zzzz-xxxx-yyyy-5003727fffff
except ZBApiException as e:
    print(f"Error submitting file: {e}")
```
```

--------------------------------

### Validate a Single Email Address with ZeroBounce SDK

Source: https://context7.com/zerobounce/zero-bounce-python-sdk-setup/llms.txt

Use this to validate a single email address. Provide your API key and the email to validate. Optionally, include the sign-up IP address for more detailed analysis. Handles API exceptions.

```python
from zerobouncesdk import ZeroBounce, ZBApiException, ZBValidateStatus

zero_bounce = ZeroBounce("your_api_key_here")

try:
    response = zero_bounce.validate("john.doe@example.com", ip_address="99.110.204.1")
    print(f"Address: {response.address}")
    print(f"Status: {response.status}")           # e.g. ZBValidateStatus.valid
    print(f"Sub-status: {response.sub_status}")
    print(f"Free email: {response.free_email}")
    print(f"MX found: {response.mx_found}")
    print(f"SMTP provider: {response.smtp_provider}")
    print(f"Did you mean: {response.did_you_mean}")
    print(f"Domain age (days): {response.domain_age_days}")
    print(f"Processed at: {response.processed_at}")

    if response.status == ZBValidateStatus.valid:
        print("Email is valid — safe to send!")
    else:
        print(f"Email is not deliverable: {response.sub_status}")
except ZBApiException as e:
    print(f"Validation error: {e}")
```

--------------------------------

### Validate Batch of Emails with ZeroBounce SDK

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Validate up to 100 email addresses simultaneously for efficiency. Each element in the batch can optionally include an IP address. Ensure the batch does not exceed the limit.

```python
from zerobouncesdk import ZeroBounce, ZBException, ZBValidateBatchElement

zero_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 validate

try:
    response = zero_bounce.validate_batch(email_batch)
    print("ZeroBounce validate_batch response: " + str(response))
except ZBException as e:
    print("ZeroBounce validate_batch error: " + str(e))
```

--------------------------------

### Find Email Format (by domain)

Source: https://github.com/zerobounce/zero-bounce-python-sdk-setup/blob/master/documentation.md

Find the correct email format when you provide a name and email domain. This method uses the first name, middle name (optional), last name (optional), and domain to suggest an email format.

```python
from zerobouncesdk import ZeroBounce, ZBException

zero_bounce = ZeroBounce("<YOUR_API_KEY>")

domain = "example.com"
first_name = "John"
middle_name = "Quill"
last_name = "Doe"

try:
    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))
except ZBException as e:
    print("ZeroBounce find_email_format error: " + str(e))
```
Tokens:
Raw