NeverBounce Python SDK

Common errors

• neverbounce_sdk.auth_failure: Invalid API Key. Please provide a valid NeverBounce V4 API Key.

  cause Attempting to authenticate with a NeverBounce V3 API key (old format) or an invalid V4 API key.
  fix Ensure you are using a NeverBounce V4 API key, which begins with `secret_`. Generate a new key from your NeverBounce account if needed.

• ImportError: No module named neverbounce_sdk

  cause The `neverbounce-sdk` package is not installed or the import path is incorrect (e.g., trying `import neverbounce` instead of `import neverbounce_sdk`).
  fix Install the package using `pip install neverbounce_sdk` and ensure your import statement is `import neverbounce_sdk`.

• requests.exceptions.ConnectionError: ('Connection aborted.', error(104, 'Connection reset by peer')) or requests.exceptions.Timeout

  cause Network connectivity issues, firewall blocking the connection, or the NeverBounce API endpoint timing out. The SDK defaults to a 30-second timeout.
  fix Check your internet connection, firewall settings, and ensure the NeverBounce API is reachable. You can also adjust the `timeout` parameter when initializing the client (e.g., `client = neverbounce_sdk.client(api_key=api_key, timeout=60)` for a longer timeout).

• KeyError: 'result' (when accessing `resp['result']`)

  cause The API response structure was unexpected, possibly due to an API error that didn't raise a `neverbounce_sdk.nb_error`, or an empty/malformed response.
  fix Implement robust error handling around API calls. Check for `neverbounce_sdk.nb_error` exceptions and inspect the raw response object if available to debug the actual API response content in case of unexpected keys.

Warnings

• breaking NeverBounce V3 API keys (8-character username or 12-16 character secret key) are incompatible with the V4 API. Using a V3 key with this SDK will result in an `auth_failure` error.
  Fix: Generate a new V4 API key from the NeverBounce dashboard, which will start with `secret_`.
• gotcha Handling 'Accept All' (catch-all) email addresses requires careful consideration. NeverBounce identifies these as 'unverifiable' because the domain is configured to accept all emails, making definitive validation impossible. Sending to these emails can still lead to high bounce rates if your email provider requires a low bounce rate (e.g., below 4%).
  Fix: Review the `result` codes, specifically `accept_all` (numeric code 3), and adjust your sending strategy based on your email provider's bounce rate tolerance and your dedicated email server setup.
• deprecated Although version 4.2.6 included a fix for Python 2.7, Python 2.7 is End-of-Life (EOL). While the SDK might still function, it's strongly recommended to use Python 3.6 or higher for security and ongoing support.
  Fix: Migrate your application to Python 3.6 or a newer supported Python version.
• gotcha Exposing your NeverBounce API key in client-side code (e.g., JavaScript in a web browser) is a security risk. The Python SDK is intended for server-side use.
  Fix: Always use the NeverBounce API key on your backend servers. For client-side verification, use the official NeverBounce JavaScript Widget, which handles API key security.

Install

• pip install neverbounce_sdk Install via pip

Imports

• client
  wrong:

  from neverbounce import NeverBounce

  correct:

  import neverbounce_sdk
  client = neverbounce_sdk.client(...)

  The official SDK uses `neverbounce_sdk.client`. `from neverbounce import NeverBounce` refers to an older, unofficial wrapper that may not be compatible with the V4 API.

Quickstart

Initialize the NeverBounce client with your V4 API key, then perform common operations like fetching account information or verifying a single email address. Ensure your API key is prefixed with `secret_`.

import neverbounce_sdk
import os

# It's recommended to store your API key in an environment variable
api_key = os.environ.get('NEVERBOUNCE_API_KEY', 'secret_YOUR_API_KEY_HERE')

if not api_key.startswith('secret_') or 'YOUR_API_KEY_HERE' in api_key:
    print("Warning: Please replace 'secret_YOUR_API_KEY_HERE' with your actual NeverBounce V4 API key or set the NEVERBOUNCE_API_KEY environment variable.")
    print("You can generate a V4 API key at: https://app.neverbounce.com/apps/custom-integration/new")
else:
    try:
        client = neverbounce_sdk.client(api_key=api_key, timeout=30)
        
        # Get account info
        info = client.account_info()
        print(f"Account Info: {info}")

        # Verify a single email
        test_email = 'test@example.com'
        resp = client.single_check(test_email)
        print(f"Verification for {test_email}: Result = {resp['result']}, Execution Time = {resp['execution_time']}ms")

    except neverbounce_sdk.auth_failure as e:
        print(f"Authentication Error: {e}. Check your API key.")
    except neverbounce_sdk.nb_error as e:
        print(f"NeverBounce API Error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")