{"id":7878,"library":"zerobouncesdk","title":"ZeroBounce Python SDK","description":"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.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/zerobounce/zero-bounce-python-sdk-setup","tags":["email verification","zerobounce","api","validation","email marketing"],"install":[{"cmd":"pip install zerobouncesdk","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"ZeroBounce","correct":"from zerobouncesdk import ZeroBounce"},{"note":"Used for specifying different ZeroBounce API regions (e.g., USA, EU).","symbol":"ZBApiUrl","correct":"from zerobouncesdk import ZBApiUrl"},{"note":"Base exception class for ZeroBounce API errors.","symbol":"ZBException","correct":"from zerobouncesdk import ZBException"}],"quickstart":{"code":"import os\nfrom zerobouncesdk import ZeroBounce, ZBException\n\nAPI_KEY = os.environ.get('ZEROBOUNCE_API_KEY', 'YOUR_API_KEY')\n\nif API_KEY == 'YOUR_API_KEY':\n    print(\"Please set the ZEROBOUNCE_API_KEY environment variable or replace 'YOUR_API_KEY'.\")\nelse:\n    try:\n        zero_bounce = ZeroBounce(API_KEY)\n        # Get credit balance\n        response = zero_bounce.get_credits()\n        if response.get('success'):\n            print(f\"Remaining Credits: {response.get('credits')}\")\n        else:\n            print(f\"Error getting credits: {response.get('message')}\")\n            if response.get('errors'):\n                for error in response.get('errors'):\n                    print(f\" - {error.get('field')}: {error.get('message')}\")\n\n        # Example: Validate a single email (replace with a real email for testing)\n        email_to_validate = 'test@example.com'\n        ip_address = '127.0.0.1'\n        validation_response = zero_bounce.validate(email_to_validate, ip_address)\n        if validation_response.get('success'):\n            print(f\"Validation for {email_to_validate}: Status = {validation_response.get('status')}, Sub Status = {validation_response.get('sub_status')}\")\n        else:\n            print(f\"Error validating {email_to_validate}: {validation_response.get('message')}\")\n\n    except ZBException as e:\n        print(f\"An SDK exception occurred: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install zerobouncesdk` to install the library.","cause":"The `zerobouncesdk` package is not installed in your Python environment.","error":"ModuleNotFoundError: No module named 'zerobouncesdk'"},{"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.","cause":"The API key provided to the `ZeroBounce` constructor is incorrect, expired, or revoked.","error":"ZeroBounce get_credits response: {'success': False, 'message': 'Invalid API Key'}"},{"fix":"Review the specific method's documentation (e.g., `validate(email, ip_address)`) to ensure all required arguments are provided and correctly formatted.","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.","error":"Error getting credits: Missing key request attributes"}]}