### Install NeverBounce Python SDK

Source: https://github.com/neverbounce/neverbounceapi-python/blob/master/README.rst

Instructions for installing the NeverBounce Python SDK using pip for general use or for local development. It also outlines the command for cloning the repository and performing an editable installation.

```shell
pip install neverbounce_sdk
```

```shell
git clone git@github.com:NeverBounce/NeverBounceApi-Python.git
cd NeverBounceApi-Python
pip install -e .
```

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

### Create and Manage Bulk Email Verification Jobs (Python)

Source: https://github.com/neverbounce/neverbounceapi-python/blob/master/README.rst

Demonstrates the process of creating a bulk email verification job, parsing it (optionally starting automatically), starting the job, and checking its status using the NeverBounce Python SDK. It highlights the structure of email input data, including optional metadata.

```python
emails = [
    {'email': 'tomato@veggies.com'},
    {'email': 'cucumber@veggies.com',
    'best_when': 'cold'},
]
job = client.jobs_create(emails)

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

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

### Bulk Job Creation

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Create bulk email verification jobs from lists of emails or remote URLs. Options control parsing, starting, and callback notifications.

```APIDOC
## Bulk Job Creation

Create bulk email verification jobs from lists or remote URLs

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

# Create job from list with metadata
emails = [
    {'email': 'support@neverbounce.com', 'id': '12345', 'name': 'Fred McValid'},
    {'email': 'invalid@neverbounce.com', 'id': '12346', 'name': 'Bob McInvalid'},
    {'email': 'disposable@example.com', 'id': '12347'}
]

resp = client.jobs_create(
    input=emails,
    filename="Customer_List.csv",
    auto_parse=False,        # Don't parse immediately
    auto_start=False,        # Don't start verification immediately
    as_sample=False,         # Process all emails (not just a sample)
    historical_data=True,    # Use historical verification data
    allow_manual_review=True,  # Allow manual review if needed
    callback_url='https://example.com/webhook',  # Webhook for completion
    callback_headers={'Authorization': 'Bearer token123'}  # Custom headers
)

print(resp['job_id'])  # Job ID for tracking
# Response: {'status': 'success', 'job_id': 289022, 'execution_time': 142}

# Create job from remote URL
url_job = client.jobs_create(
    input='https://example.com/emails.csv',
    from_url=True,
    auto_parse=True,
    auto_start=True
)
```

### Description
Initiates a bulk email verification job, either from a provided list of emails or a remote URL.

### Method
POST

### Endpoint
`/bulk/register`

### Parameters
#### Request Body
- **input** (string or array) - Required - Either a URL to a file containing emails, or a list of dictionaries, where each dictionary represents an email and optionally associated metadata ('id', 'name').
- **filename** (string) - Optional - The name to assign to the uploaded file or job.
- **from_url** (boolean) - Optional - Set to true if the `input` is a URL.
- **auto_parse** (boolean) - Optional - If true, the system will attempt to parse the input file/URL immediately. Defaults to false.
- **auto_start** (boolean) - Optional - If true, the verification process will start automatically after parsing. Defaults to false.
- **as_sample** (boolean) - Optional - If true, only a sample of the list will be processed. Defaults to false.
- **historical_data** (boolean) - Optional - If true, historical verification data will be used.
- **allow_manual_review** (boolean) - Optional - If true, allows for manual review of uncertain results.
- **callback_url** (string) - Optional - A URL to send a webhook notification to when the job is completed.
- **callback_headers** (object) - Optional - Custom headers to include with the callback request.

### Request Example
```json
// Example 1: Creating a job from a list of emails with metadata
{
  "input": [
    {"email": "support@neverbounce.com", "id": "12345", "name": "Fred McValid"},
    {"email": "invalid@neverbounce.com", "id": "12346", "name": "Bob McInvalid"}
  ],
  "filename": "Customer_List.csv",
  "auto_parse": false,
  "auto_start": false,
  "historical_data": true,
  "callback_url": "https://example.com/webhook",
  "callback_headers": {"Authorization": "Bearer token123"}
}

// Example 2: Creating a job from a remote URL
{
  "input": "https://example.com/emails.csv",
  "from_url": true,
  "auto_parse": true,
  "auto_start": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the request ('success' or 'error').
- **job_id** (integer) - The unique identifier for the created bulk verification job.
- **execution_time** (integer) - The time taken for the API call in milliseconds.

#### Response Example
```json
{
    "status": "success",
    "job_id": 289022,
    "execution_time": 142
}
```
```

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

### Handle NeverBounce API Errors via Python

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Demonstrates error handling for various NeverBounce API exceptions, including authentication failures, rate limiting, bad referrers, and general API errors. Includes examples of network and unexpected error handling.

```python
import neverbounce_sdk
from neverbounce_sdk import (
    AuthFailure,
    ThrottleTriggered,
    BadReferrer,
    GeneralException
)

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

try:
    result = client.single_check('test@example.com')
    print(result)

except AuthFailure as e:
    print(f"Authentication failed: {e.message}")
    print(f"Execution time: {e.execution_time}ms")
    # Bad API key or credentials issue

except ThrottleTriggered as e:
    print(f"Rate limit exceeded: {e.message}")
    # Too many requests, implement backoff and retry
    import time
    time.sleep(5)

except BadReferrer as e:
    print(f"Unauthorized source: {e.message}")
    # Script running from unauthorized domain

except GeneralException as e:
    print(f"API error: {e.message}")
    print(f"Execution time: {e.execution_time}ms")
    # Other API errors

except Exception as e:
    print(f"Unexpected error: {str(e)}")
    # Network errors, timeouts, etc.
```

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

### Verify Single Email with NeverBounce Python SDK

Source: https://github.com/neverbounce/neverbounceapi-python/blob/master/README.rst

Provides an example of verifying a single email address using the NeverBounce Python SDK, including retrieving the verification result and execution time.

```python
resp = client.single_check('test@example.com')
resp['result']              # 'invalid'
resp['execution_time']      # 285
```

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

### Accessing Client Function Documentation (Python)

Source: https://github.com/neverbounce/neverbounceapi-python/blob/master/README.rst

Illustrates how to access detailed documentation for client functions using Python's built-in `help()` function. This is useful for understanding function arguments, options, and return values, complementing the official API documentation.

```python
help(client.create)
```

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

### Initialize NeverBounce API Client (Python)

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Demonstrates initializing the NeverBounce API client using various configurations including basic initialization, custom timeouts, custom sessions for connection pooling, and context manager support for automatic session management.

```python
import neverbounce_sdk

# Basic initialization
api_key = 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
client = neverbounce_sdk.client(api_key=api_key)

# With custom timeout (in seconds)
client = neverbounce_sdk.client(api_key=api_key, timeout=30)

# With custom session for connection pooling
from requests import Session
session = Session()
client = neverbounce_sdk.client(api_key=api_key, session=session)

# Using context manager (automatically creates and closes session)
with neverbounce_sdk.client(api_key=api_key) as client:
    info = client.account_info()
    print(info)
# Session is automatically closed after the with block
```

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

### Initialize NeverBounce Python Client

Source: https://github.com/neverbounce/neverbounceapi-python/blob/master/README.rst

Demonstrates how to initialize the NeverBounce client with an API key and an optional timeout. It also shows how to initialize the client with a custom requests.Session object for connection pooling.

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

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

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

### Client Initialization

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Initialize the NeverBounce API client using your API key. Supports basic initialization, custom timeouts, and session management.

```APIDOC
## Client Initialization

Initialize the NeverBounce API client with your API key

```python
import neverbounce_sdk

# Basic initialization
api_key = 'secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
client = neverbounce_sdk.client(api_key=api_key)

# With custom timeout (in seconds)
client = neverbounce_sdk.client(api_key=api_key, timeout=30)

# With custom session for connection pooling
from requests import Session
session = Session()
client = neverbounce_sdk.client(api_key=api_key, session=session)

# Using context manager (automatically creates and closes session)
with neverbounce_sdk.client(api_key=api_key) as client:
    info = client.account_info()
    print(info)
# Session is automatically closed after the with block
```
```

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

### Verify Single Email Address (Python)

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Illustrates how to verify a single email address in real-time. Includes options for including address information, credit status, historical data, and custom timeouts.

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

# Basic email verification
resp = client.single_check('test@example.com')
print(resp['result'])  # Returns: 'invalid', 'valid', 'disposable', 'catchall', or 'unknown'
print(resp['execution_time'])  # Time in milliseconds

# With additional options
verification = client.single_check(
    email='support@neverbounce.com',
    address_info=True,      # Include detailed address information
    credits_info=True,      # Include remaining credits
    historical_data=False,  # Don't use historical data
    timeout=10              # API timeout in seconds
)

# Expected response:
# {
#     'status': 'success',
#     'result': 'valid',
#     'flags': ['has_dns', 'has_dns_mx', 'smtp_connectable'],
#     'suggested_correction': '',
#     'execution_time': 285,
#     'credits_info': {
#         'paid_credits_used': 1,
#         'free_credits_used': 0,
#         'paid_credits_remaining': 12344,
#         'free_credits_remaining': 0
#     },
#     'address_info': {
#         'original_email': 'support@neverbounce.com',
#         'normalized_email': 'support@neverbounce.com',
#         'addr': 'support',
#         'alias': '',
#         'host': 'neverbounce.com',
#         'fqdn': 'neverbounce.com',
#         'domain': 'neverbounce',
#         'subdomain': '',
#         'tld': 'com'
#     }
# }
```

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

### Retrieve Account Information (Python)

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Shows how to fetch account details such as available credits, billing type, and the number of jobs completed or processing using the NeverBounce API client.

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

# Get account information
info = client.account_info()
print(info)

# Expected response:
# {
#     'status': 'success',
#     'billing_type': 'default',
#     'credits': 12345,
#     'jobs_completed': 450,
#     'jobs_processing': 2,
#     'execution_time': 142
# }
```

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

### Iterate Through All Jobs with NeverBounce Python SDK

Source: https://github.com/neverbounce/neverbounceapi-python/blob/master/README.rst

Explains how to use the `jobs_search` method to retrieve all verification jobs and iterate through them using a custom `ResultIter` object. It also shows how to access pagination details like current page and total pages, and mentions the `raw_search` and `raw_results` methods for accessing raw API responses.

```python
all_my_jobs = client.jobs_search()
type(all_my_jobs)       # neverbounce_sdk.bulk.ResultIter
for job in all_my_jobs:
    # process job
    if all_my_jobs.page > 10:
        break
```

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

### Create Bulk Email Verification Jobs (Python)

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Details on creating bulk email verification jobs, either from a list of emails with associated metadata or from a remote URL. Supports options for auto-parsing, auto-starting, using historical data, and configuring webhooks for completion notifications.

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

# Create job from list with metadataemails = [
    {'email': 'support@neverbounce.com', 'id': '12345', 'name': 'Fred McValid'},
    {'email': 'invalid@neverbounce.com', 'id': '12346', 'name': 'Bob McInvalid'},
    {'email': 'disposable@example.com', 'id': '12347'}
]

resp = client.jobs_create(
    input=emails,
    filename="Customer_List.csv",
    auto_parse=False,        # Don't parse immediately
    auto_start=False,        # Don't start verification immediately
    as_sample=False,         # Process all emails (not just a sample)
    historical_data=True,    # Use historical verification data
    allow_manual_review=True,  # Allow manual review if needed
    callback_url='https://example.com/webhook',  # Webhook for completion
    callback_headers={'Authorization': 'Bearer token123'}  # Custom headers
)

print(resp['job_id'])  # Job ID for tracking
# Response: {'status': 'success', 'job_id': 289022, 'execution_time': 142}

# Create job from remote URL
url_job = client.jobs_create(
    input='https://example.com/emails.csv',
    from_url=True,
    auto_parse=True,
    auto_start=True
)
```

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

### Check Account Information with NeverBounce Python SDK

Source: https://github.com/neverbounce/neverbounceapi-python/blob/master/README.rst

Shows how to retrieve account information, such as billing type and available credits, using the NeverBounce Python SDK client.

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

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

### Download Invalids and Catchalls

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Downloads a CSV file containing invalid and catchall email addresses from a completed verification job, with various append options and specified formatting.

```APIDOC
## Download Invalids and Catchalls

This endpoint allows you to download the results of a verification job, specifically filtering for invalid and catchall email addresses. You can also specify various appends to include additional information about each email address in the downloaded file.

### Method
POST

### Endpoint
/jobs/download

### Parameters
#### Query Parameters
- **job_id** (integer) - Required - The ID of the verification job to download.
- **segmentation** (string) - Optional - Comma-separated list of segments to include. Supported values: `invalids`, `catchalls`, `unknowns`, `only_duplicates`.
- **appends** (string) - Optional - Comma-separated list of appends to include. Supported values: `bad_syntax`, `free_email_host`, `role_account`, `addr`, `host`, `domain`, `tld`, `has_dns_info`, `has_mail_server`, `email_status`.
- **yes_no_representation** (string) - Optional - Representation for boolean values. Use `bool` for `true`/`false` or `numeric` for `1`/`0`.
- **line_feed_type** (string) - Optional - Specifies the line ending type for the CSV file. Use `windows` for `\r\n` or `unix` for `\n`.

### Request Example
```python
client.jobs_download(
    job_id=job_id,
    fd=f,
    segmentation=('invalids', 'catchalls', 'unknowns'),
    appends=(
        'bad_syntax',
        'free_email_host',
        'role_account',
        'addr',
        'host',
        'domain',
        'tld',
        'has_dns_info',
        'has_mail_server',
        'email_status'
    ),
    yes_no_representation='bool',
    line_feed_type='windows'
)
```

### Response
#### Success Response (200)
Returns a file stream containing the downloaded CSV data.

#### Response Example
(CSV file content)
```

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

### Using NeverBounce Client as a Context Manager (Python)

Source: https://github.com/neverbounce/neverbounceapi-python/blob/master/README.rst

Demonstrates how to use the NeverBounce client as a context manager. When used in a `with` block, a session is automatically created and managed. The session is guaranteed to be closed at the end of the block, even if no session was initially provided.

```python
import neverbounce_sdk

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

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

### Error Handling API

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Demonstrates how to handle various API errors and exceptions that may occur when using the NeverBounce Python SDK.

```APIDOC
## Error Handling

Handle API errors and exceptions gracefully to ensure robust application behavior.

### Method
N/A (Client-side error handling)

### Endpoint
N/A

### Description
This section outlines common exceptions raised by the NeverBounce Python SDK and provides guidance on how to handle them.

### Exception Types
- **AuthFailure**: Authentication failed (e.g., invalid API key).
- **ThrottleTriggered**: Rate limit exceeded. Implement backoff and retry.
- **BadReferrer**: Script running from an unauthorized domain.
- **GeneralException**: Other general API errors.
- **Exception**: Catches unexpected errors like network issues or timeouts.

### Request Example (Illustrative Try-Except Block)
```python
from neverbounce_sdk import (
    AuthFailure,
    ThrottleTriggered,
    BadReferrer,
    GeneralException
)

try:
    result = client.single_check('test@example.com')
    print(result)

except AuthFailure as e:
    print(f"Authentication failed: {e.message}")
    print(f"Execution time: {e.execution_time}ms")

except ThrottleTriggered as e:
    print(f"Rate limit exceeded: {e.message}")
    # Implement backoff and retry logic here
    import time
    time.sleep(5)

except BadReferrer as e:
    print(f"Unauthorized source: {e.message}")

except GeneralException as e:
    print(f"API error: {e.message}")
    print(f"Execution time: {e.execution_time}ms")

except Exception as e:
    print(f"Unexpected error: {str(e)}")
```

### Response
Error messages and execution times printed to the console, depending on the exception caught.
```

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

### Account Information

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Retrieve account details, including available credits, billing type, and ongoing job statuses.

```APIDOC
## Account Information

Retrieve account details including credits and billing type

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

# Get account information
info = client.account_info()
print(info)

# Expected response:
# {
#     'status': 'success',
#     'billing_type': 'default',
#     'credits': 12345,
#     'jobs_completed': 450,
#     'jobs_processing': 2,
#     'execution_time': 142
# }
```

### Description
Fetches the current account status, including credit balance and job statistics.

### Method
GET

### Endpoint
`/account/info`

### Parameters
No parameters required for this endpoint.

### Request Example
```python
# No request body or query parameters needed for basic account info retrieval.
# Example call:
# client.account_info()
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the request ('success' or 'error').
- **billing_type** (string) - The type of billing plan associated with the account.
- **credits** (integer) - The number of available verification credits.
- **jobs_completed** (integer) - The total number of verification jobs completed.
- **jobs_processing** (integer) - The number of verification jobs currently in progress.
- **execution_time** (integer) - The time taken for the API call in milliseconds.

#### Response Example
```json
{
    "status": "success",
    "billing_type": "default",
    "credits": 12345,
    "jobs_completed": 450,
    "jobs_processing": 2,
    "execution_time": 142
}
```
```

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

### Confirm Proof of Execution (POE) via Python

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Confirms client-side verifications performed by the JavaScript widget. This helps prevent replay attacks and ensures the verification was legitimate. Requires email, transaction ID, confirmation token, and result.

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

# Confirm a verification performed by the JavaScript widget
resp = client.poe_confirm(
    email='user@example.com',
    transaction_id='5f9a8b7c6d5e4f3a2b1c0d9e',
    confirmation_token='abcdef123456',
    result='valid'
)

print(resp)
# Response: {'status': 'success', 'execution_time': 45}

# This prevents replay attacks and confirms the verification was legitimate
```

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

### Download Duplicates Only

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Downloads a CSV file containing only the duplicate email addresses from a verification job.

```APIDOC
## Download Duplicates Only

This endpoint allows you to download a CSV file containing only the duplicate email addresses identified during a verification job.

### Method
POST

### Endpoint
/jobs/download

### Parameters
#### Query Parameters
- **job_id** (integer) - Required - The ID of the verification job to download.
- **segmentation** (string) - Required - Set to `only_duplicates` to download only duplicate email addresses.

### Request Example
```python
client.jobs_download(
    job_id=job_id,
    fd=f,
    segmentation=('only_duplicates',)
)
```

### Response
#### Success Response (200)
Returns a file stream containing the downloaded CSV data with only duplicate email addresses.

#### Response Example
(CSV file content)
```

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

### Proof of Execution (POE) Confirmation API

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Confirms client-side verifications performed by the NeverBounce JavaScript widget. This helps prevent replay attacks and ensures the legitimacy of verifications.

```APIDOC
## Proof of Execution (POE) Confirmation

Confirm client-side verifications from the JavaScript widget to prevent replay attacks and ensure legitimacy.

### Method
POST

### Endpoint
/poe/confirm

### Parameters
#### Request Body
- **email** (string) - Required - The email address that was verified.
- **transaction_id** (string) - Required - The unique transaction ID generated by the JavaScript widget.
- **confirmation_token** (string) - Required - The confirmation token provided by the JavaScript widget.
- **result** (string) - Required - The result of the verification ('valid', 'invalid', 'catchall', etc.).

### Request Example
```python
client.poe_confirm(
    email='user@example.com',
    transaction_id='5f9a8b7c6d5e4f3a2b1c0d9e',
    confirmation_token='abcdef123456',
    result='valid'
)
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the confirmation, e.g., 'success'.
- **execution_time** (integer) - The time taken for the operation in milliseconds.

#### Response Example
```json
{
  "status": "success",
  "execution_time": 45
}
```
```

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

### Single Email Verification

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Verify individual email addresses in real-time using various options to control the verification process and included data.

```APIDOC
## Single Email Verification

Verify individual email addresses in real-time

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

# Basic email verification
resp = client.single_check('test@example.com')
print(resp['result'])  # Returns: 'invalid', 'valid', 'disposable', 'catchall', or 'unknown'
print(resp['execution_time'])  # Time in milliseconds

# With additional options
verification = client.single_check(
    email='support@neverbounce.com',
    address_info=True,      # Include detailed address information
    credits_info=True,      # Include remaining credits
    historical_data=False,  # Don't use historical data
    timeout=10              # API timeout in seconds
)

# Expected response:
# {
#     'status': 'success',
#     'result': 'valid',
#     'flags': ['has_dns', 'has_dns_mx', 'smtp_connectable'],
#     'suggested_correction': '',
#     'execution_time': 285,
#     'credits_info': {
#         'paid_credits_used': 1,
#         'free_credits_used': 0,
#         'paid_credits_remaining': 12344,
#         'free_credits_remaining': 0
#     },
#     'address_info': {
#         'original_email': 'support@neverbounce.com',
#         'normalized_email': 'support@neverbounce.com',
#         'addr': 'support',
#         'alias': '',
#         'host': 'neverbounce.com',
#         'fqdn': 'neverbounce.com',
#         'domain': 'neverbounce',
#         'subdomain': '',
#         'tld': 'com'
#     }
# }
```

### Description
Verifies the status of a single email address in real-time.

### Method
GET

### Endpoint
`/verifier/check`

### Parameters
#### Query Parameters
- **email** (string) - Required - The email address to verify.
- **address_info** (boolean) - Optional - If true, includes detailed address parsing information in the response.
- **credits_info** (boolean) - Optional - If true, includes remaining credit information in the response.
- **historical_data** (boolean) - Optional - If true, attempts to use cached historical verification data.
- **timeout** (integer) - Optional - The timeout in seconds for the API request.

### Request Example
```python
# Basic request
# client.single_check('test@example.com')

# Request with options
# client.single_check(
#     email='support@neverbounce.com',
#     address_info=True,
#     credits_info=True,
#     historical_data=False,
#     timeout=10
# )
```

### Response
#### Success Response (200)
- **status** (string) - The overall status of the verification request ('success' or 'error').
- **result** (string) - The verification result ('valid', 'invalid', 'disposable', 'catchall', 'unknown').
- **flags** (array) - A list of flags indicating properties of the email address (e.g., 'has_dns', 'smtp_connectable').
- **suggested_correction** (string) - A suggested correction if a typo is detected.
- **execution_time** (integer) - The time in milliseconds the verification took.
- **credits_info** (object) - Optional. Contains details about credits used and remaining.
  - **paid_credits_used** (integer) - Paid credits consumed by this verification.
  - **free_credits_used** (integer) - Free credits consumed by this verification.
  - **paid_credits_remaining** (integer) - Remaining paid credits.
  - **free_credits_remaining** (integer) - Remaining free credits.
- **address_info** (object) - Optional. Contains parsed information about the email address.
  - **original_email** (string) - The email address as provided.
  - **normalized_email** (string) - The normalized version of the email address.
  - **addr** (string) - The local part of the email address.
  - **alias** (string) - The alias part of the email address, if any.
  - **host** (string) - The hostname part of the email address.
  - **fqdn** (string) - The fully qualified domain name.
  - **domain** (string) - The domain part of the email address.
  - **subdomain** (string) - The subdomain part, if any.
  - **tld** (string) - The top-level domain.

#### Response Example
```json
{
    "status": "success",
    "result": "valid",
    "flags": ["has_dns", "has_dns_mx", "smtp_connectable"],
    "suggested_correction": "",
    "execution_time": 285,
    "credits_info": {
        "paid_credits_used": 1,
        "free_credits_used": 0,
        "paid_credits_remaining": 12344,
        "free_credits_remaining": 0
    },
    "address_info": {
        "original_email": "support@neverbounce.com",
        "normalized_email": "support@neverbounce.com",
        "addr": "support",
        "alias": "",
        "host": "neverbounce.com",
        "fqdn": "neverbounce.com",
        "domain": "neverbounce",
        "subdomain": "",
        "tld": "com"
    }
}
```
```

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

### Download Only Duplicate Emails via Python

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Downloads only duplicate email addresses from a specified job ID into a CSV file. This is useful for identifying and managing duplicate entries within a dataset.

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
job_id = 12345

with open('duplicates.csv', mode='wb') as f:
    client.jobs_download(
        job_id=job_id,
        fd=f,
        segmentation=('only_duplicates',)
    )
```

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

### Download Invalid and Catchall Emails via Python

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Downloads invalid and catchall email addresses from a specified job ID into a CSV file. Supports various append options and line ending types. This function is useful for cleaning email lists.

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
job_id = 12345

with open('problematic.csv', mode='wb') as f:
    client.jobs_download(
        job_id=job_id,
        fd=f,
        segmentation=('invalids', 'catchalls', 'unknowns'),
        appends=(
            'bad_syntax',
            'free_email_host',
            'role_account',
            'addr',
            'host',
            'domain',
            'tld',
            'has_dns_info',
            'has_mail_server',
            'email_status'
        ),
        yes_no_representation='bool',  # Use true/false instead of 1/0
        line_feed_type='windows'       # Use Windows line endings (\r\n)
    )
```

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

### Job Deletion API

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Permanently deletes a verification job and all associated data. Use with caution as this action is irreversible.

```APIDOC
## Job Deletion

Permanently delete verification jobs and all associated data.

### Method
POST

### Endpoint
/jobs/delete

### Parameters
#### Path Parameters
- **job_id** (integer) - Required - The ID of the job to delete.

### Request Example
```python
client.jobs_delete(job_id=job_id)
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation, e.g., 'success'.
- **execution_time** (integer) - The time taken for the operation in milliseconds.

#### Response Example
```json
{
  "status": "success",
  "execution_time": 67
}
```
```

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

### Delete Verification Jobs via Python

Source: https://context7.com/neverbounce/neverbounceapi-python/llms.txt

Permanently deletes a verification job and all associated data using its job ID. This operation is irreversible and should be used with caution.

```python
import neverbounce_sdk

client = neverbounce_sdk.client(api_key='secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

job_id = 289022

# Delete a job
resp = client.jobs_delete(job_id=job_id)
print(resp)
# Response: {'status': 'success', 'execution_time': 67}

# Note: This permanently deletes the job and all associated data
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.