# What changed in zerobouncesdk

> 47 changes in zerobouncesdk 2 from its official release notes, upgrade guides and advisories: 10 breaking, 1 deprecations, 2 security, 29 new APIs and options. Each one cited. Sources checked 2026-10-25. HTML: https://unstale.sh/pypi/zerobouncesdk/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## zerobouncesdk 2

### Breaking changes

- Custom base_url values must start with https://; otherwise ZeroBounce(...) raises ZBClientException. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Minimum dependency versions increased to releases without known advisories, with lower requests and idna floors on Python 3.7–3.9. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- An HTML page returned by the API, including with status 200, now raises instead of being saved as a CSV. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- An HTML page returned by the API, including with status 200, now raises instead of being saved as a CSV. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- SFTP jobs require file_name. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- A Message error now raises instead of passing through as a result. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- An HTML page returned by the API, including with status 200, now raises instead of being saved as a CSV. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Requests time out after 120 seconds unless timeout is passed, and redirects are no longer followed. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- S3/SFTP jobs require return_url. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Account-level failures, such as an invalid API key or no credits, now raise ZBApiException; single-address errors remain in the result. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)

### Security

- The API key is excluded from exception messages and chained exceptions. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Inbox Placement Tester calls send the key in the Authorization: Bearer header instead of the URL. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)

### Deprecations

- A UserWarning is emitted when an EU or US base_url is set while bulk requests still use bulkapi.zerobounce.net. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)

### New APIs and options

- A new ai_agent_mailbox sub-status is supported. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Amazon S3 bulk job functionality is newly available. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Bulk domain search functionality is newly available. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Bulk email finder functionality is newly available. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Filters functionality is newly available. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- find_domain accepts use_post=True to make POST requests. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- find_email_format accepts use_post=True to make POST requests. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- get_activity accepts use_post=True to make POST requests. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- get_api_usage accepts use_post=True to make POST requests. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- get_credits accepts use_post=True to make POST requests. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- The four *get_file methods accept stream=True; the file appears only after the download completes. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Inbox Placement Tester functionality is newly available. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- List Evaluator functionality is newly available. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- A new method provides AI scoring. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- SFTP/FTP bulk job functionality is newly available. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate now accepts activity_data. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate_batch now accepts activity_data. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate_batch now accepts timeout; the SDK sends it as a string. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate_batch now accepts verify_plus. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate now accepts callback_url. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate now accepts domain_info. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate now accepts greylist_processing. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate now accepts timeout. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate now accepts use_post. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- validate now accepts verify_plus. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- ZBApiException.status_code exposes the HTTP status of a failed request. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- A client for all 26 Warmup API endpoints is available; it uses its own key in the API-Key header. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Adds the Gold sub-status to the SDK. (2.0.1) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.0.1)
- Adds role_based_accept_all as a sub status. (2.0.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.0.0)

### Behavior and default changes

- The find domain functionality was updated. (2.0.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.0.0)
- The find email functionality was updated. (2.0.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.0.0)

### Fixes and other changes

- check_domain_dmarc takes an email address. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- Importing on Python 3.7–3.9 works again; it raised TypeError in 2.2.x. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)
- send_evaluated_file takes the evaluator's file_id. (2.3.0) — [release notes](https://github.com/zerobounce/zero-bounce-python-sdk-setup/releases/tag/v2.3.0)