{"id":8348,"library":"neverbounce-sdk","title":"NeverBounce Python SDK","description":"The official Python SDK for the NeverBounce API (version 4) provides a streamlined interface for email verification. It supports both single email checks and bulk list processing, aiming to improve email deliverability and sender reputation. The library is actively maintained, with the current version being 4.3.0, and includes bug fixes and documentation updates.","status":"active","version":"4.3.0","language":"en","source_language":"en","source_url":"https://github.com/NeverBounce/NeverBounceApi-Python","tags":["email verification","API client","email validation","deliverability","marketing"],"install":[{"cmd":"pip install neverbounce_sdk","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Handles HTTP requests to the NeverBounce API.","package":"requests","optional":false},{"reason":"Provides Python 2 and 3 compatibility utilities.","package":"six","optional":false}],"imports":[{"note":"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.","wrong":"from neverbounce import NeverBounce","symbol":"client","correct":"import neverbounce_sdk\nclient = neverbounce_sdk.client(...)"}],"quickstart":{"code":"import neverbounce_sdk\nimport os\n\n# It's recommended to store your API key in an environment variable\napi_key = os.environ.get('NEVERBOUNCE_API_KEY', 'secret_YOUR_API_KEY_HERE')\n\nif not api_key.startswith('secret_') or 'YOUR_API_KEY_HERE' in api_key:\n    print(\"Warning: Please replace 'secret_YOUR_API_KEY_HERE' with your actual NeverBounce V4 API key or set the NEVERBOUNCE_API_KEY environment variable.\")\n    print(\"You can generate a V4 API key at: https://app.neverbounce.com/apps/custom-integration/new\")\nelse:\n    try:\n        client = neverbounce_sdk.client(api_key=api_key, timeout=30)\n        \n        # Get account info\n        info = client.account_info()\n        print(f\"Account Info: {info}\")\n\n        # Verify a single email\n        test_email = 'test@example.com'\n        resp = client.single_check(test_email)\n        print(f\"Verification for {test_email}: Result = {resp['result']}, Execution Time = {resp['execution_time']}ms\")\n\n    except neverbounce_sdk.auth_failure as e:\n        print(f\"Authentication Error: {e}. Check your API key.\")\n    except neverbounce_sdk.nb_error as e:\n        print(f\"NeverBounce API Error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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_`."},"warnings":[{"fix":"Generate a new V4 API key from the NeverBounce dashboard, which will start with `secret_`.","message":"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.","severity":"breaking","affected_versions":"All versions (since V4 API launch)"},{"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.","message":"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%).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate your application to Python 3.6 or a newer supported Python version.","message":"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.","severity":"deprecated","affected_versions":"<= 4.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you are using a NeverBounce V4 API key, which begins with `secret_`. Generate a new key from your NeverBounce account if needed.","cause":"Attempting to authenticate with a NeverBounce V3 API key (old format) or an invalid V4 API key.","error":"neverbounce_sdk.auth_failure: Invalid API Key. Please provide a valid NeverBounce V4 API Key."},{"fix":"Install the package using `pip install neverbounce_sdk` and ensure your import statement is `import 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`).","error":"ImportError: No module named neverbounce_sdk"},{"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).","cause":"Network connectivity issues, firewall blocking the connection, or the NeverBounce API endpoint timing out. The SDK defaults to a 30-second timeout.","error":"requests.exceptions.ConnectionError: ('Connection aborted.', error(104, 'Connection reset by peer')) or requests.exceptions.Timeout"},{"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.","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.","error":"KeyError: 'result' (when accessing `resp['result']`)"}]}