v2.3.0

Upgrading from 2.2.x

Most code keeps working unchanged. Check these first:

• A custom base_url must start with https://. Otherwise ZeroBounce(...) raises ZBClientException("base_url must be an https:// URL"). The default and ZBApiUrl values are already https.
• validate_batch raises ZBApiException for account-level failures (an invalid API key or no credits, sent by the API as an error for address all). It used to return them as a result. Errors for single addresses still come back on the result.
• Errors raise instead of passing through as results: find_email_format on a Message error, and get_file / email_finder_get_file / domain_search_get_file when the API sends an HTML page (including with status 200), which used to be saved as the CSV.
• Requests time out after 120 seconds unless you pass timeout, and redirects are not followed.
• Dependency floors went up to releases without known advisories: requests >= 2.33.0, urllib3 >= 2.8.0, idna >= 3.15 on Python 3.10+ (lower floors on 3.7–3.9, which cannot install the fixed requests 2.33), and certifi >= 2026.10.19 everywhere. Python 3.7+ is still supported, and importing on 3.7–3.9 works again (it raised TypeError in 2.2.x).

New

• validate: timeout, activity_data, verify_plus, domain_info, greylist_processing, callback_url and use_post.
• validate_batch: timeout, activity_data and verify_plus.
• New methods:
  • AI scoring: score_email.
  • Bulk email finder and bulk domain search.
  • List Evaluator.
  • Filters.
  • Amazon S3 and SFTP/FTP bulk jobs.
  • Inbox Placement Tester.
• ZeroBounceWarmup: a client for all 26 Warmup API endpoints. It uses its own key, sent in the API-Key header.
• POST requests: use_post=True on get_credits, get_api_usage, get_activity, find_email_format and find_domain.
• Streamed downloads: pass stream=True to the four *get_file methods. The file only appears once the download is complete.
• ZBApiException.status_code: the HTTP status of a failed request.
• EU/US warning: a UserWarning when you set an EU or US base_url but bulk requests still go to bulkapi.zerobounce.net. ZeroBounce documents no regional bulk host.
• ai_agent_mailbox sub-status.

Matches the live API, not the docs

Every method was called against the live API before release. Where the API and the docs disagree, the SDK follows the API:

• validate_batch sends timeout as a string.
• send_evaluated_file takes the evaluator's file_id.
• S3/SFTP jobs require return_url, and SFTP jobs require file_name.
• check_domain_dmarc takes an email address.

Security

• The API key is kept out of exception messages and chained exceptions.
• Inbox Placement Tester calls send the key in the Authorization: Bearer header, not in the URL.
• PyPI releases are published with Trusted Publishing; there is no API token.

Release check

• Live API suite: run 2026-10-24 with both keys, ZEROBOUNCE_LIVE_SPEND=1 and ZEROBOUNCE_LIVE_CHANGES=1.
• First full run: 19/20 passed. The Warmup API returns [] when a team has no sending accounts, and the test now accepts that (3f37974).
• That test was then re-run on its own and passed.
• Offline: 130 tests pass.

Full list: CHANGELOG.md

---

What's Changed

• Harden SDK logging, HTTP defaults, and CI supply chain by @franciscbalint in #24
• Bump github/codeql-action from 4.37.1 to 4.37.8 in the github group across 1 directory by @dependabot[bot] in #23
• Security audit 2026-10-14: CI hardening and Dependabot security-only by @franciscbalint in #26
• fix(ci): publish workflow CodeQL cache-poisoning by @franciscbalint in #27
• feat: v2 validate parity (verify_plus, activity_data, batch timeout) by @franciscbalint in #28
• docs: bring every doc in line with the code after API parity by @franciscbalint in #29
• fix: match what the live API accepts (every endpoint called live) by @franciscbalint in #30
• test: opt-in live API suite, and a required live run per release by @franciscbalint in #31

Full Changelog: v2.2.4...v2.3.0