unstale

pypi / zerobouncesdk

zerobouncesdk

What changed in zerobouncesdk 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-25.

10 breaking2 security1 deprecations29 new APIs and options2 behavior and defaults3 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.6 on npm

zerobouncesdk 247 changes

Breaking changes 10

  • Custom base_url values must start with https://; otherwise ZeroBounce(...) raises ZBClientException.

    2.3.0release notes

  • Minimum dependency versions increased to releases without known advisories, with lower requests and idna floors on Python 3.7–3.9.

    2.3.0release notes

  • An HTML page returned by the API, including with status 200, now raises instead of being saved as a CSV.

    2.3.0release notes

  • An HTML page returned by the API, including with status 200, now raises instead of being saved as a CSV.

    2.3.0release notes

  • SFTP jobs require file_name.

    2.3.0release notes

  • A Message error now raises instead of passing through as a result.

    2.3.0release notes

  • An HTML page returned by the API, including with status 200, now raises instead of being saved as a CSV.

    2.3.0release notes

  • Requests time out after 120 seconds unless timeout is passed, and redirects are no longer followed.

    2.3.0release notes

  • S3/SFTP jobs require return_url.

    2.3.0release notes

  • Account-level failures, such as an invalid API key or no credits, now raise ZBApiException; single-address errors remain in the result.

    2.3.0release notes

Security 2

  • The API key is excluded from exception messages and chained exceptions.

    2.3.0release notes

  • Inbox Placement Tester calls send the key in the Authorization: Bearer header instead of the URL.

    2.3.0release notes

Deprecations 1

  • A UserWarning is emitted when an EU or US base_url is set while bulk requests still use bulkapi.zerobounce.net.

    2.3.0release notes

New APIs and options 29

  • A new ai_agent_mailbox sub-status is supported.

    2.3.0release notes

  • Amazon S3 bulk job functionality is newly available.

    2.3.0release notes

  • Bulk domain search functionality is newly available.

    2.3.0release notes

  • Bulk email finder functionality is newly available.

    2.3.0release notes

  • Filters functionality is newly available.

    2.3.0release notes

  • find_domain accepts use_post=True to make POST requests.

    2.3.0release notes

  • find_email_format accepts use_post=True to make POST requests.

    2.3.0release notes

  • get_activity accepts use_post=True to make POST requests.

    2.3.0release notes

  • get_api_usage accepts use_post=True to make POST requests.

    2.3.0release notes

  • get_credits accepts use_post=True to make POST requests.

    2.3.0release notes

  • The four *get_file methods accept stream=True; the file appears only after the download completes.

    2.3.0release notes

  • Inbox Placement Tester functionality is newly available.

    2.3.0release notes

  • List Evaluator functionality is newly available.

    2.3.0release notes

  • A new method provides AI scoring.

    2.3.0release notes

  • SFTP/FTP bulk job functionality is newly available.

    2.3.0release notes

  • validate now accepts activity_data.

    2.3.0release notes

  • validate_batch now accepts activity_data.

    2.3.0release notes

  • validate_batch now accepts timeout; the SDK sends it as a string.

    2.3.0release notes

  • validate_batch now accepts verify_plus.

    2.3.0release notes

  • validate now accepts callback_url.

    2.3.0release notes

  • validate now accepts domain_info.

    2.3.0release notes

  • validate now accepts greylist_processing.

    2.3.0release notes

  • validate now accepts timeout.

    2.3.0release notes

  • validate now accepts use_post.

    2.3.0release notes

  • validate now accepts verify_plus.

    2.3.0release notes

  • ZBApiException.status_code exposes the HTTP status of a failed request.

    2.3.0release notes

  • A client for all 26 Warmup API endpoints is available; it uses its own key in the API-Key header.

    2.3.0release notes

  • Adds the Gold sub-status to the SDK.

    2.0.1release notes

  • Adds role_based_accept_all as a sub status.

    2.0.0release notes

Behavior and default changes 2

Fixes and other changes 3

  • check_domain_dmarc takes an email address.

    2.3.0release notes

  • Importing on Python 3.7–3.9 works again; it raised TypeError in 2.2.x.

    2.3.0release notes

  • send_evaluated_file takes the evaluator's file_id.

    2.3.0release notes