[franciscbalint]

Summary

Priority 1–2 parity on feature/api-parity-p1-validate (validate options, score_email).

Priority 3 — bulk finder, list evaluator, filters, S3

• Bulk email finder: send_email_finder_file / _stream, email_finder_file_status, email_finder_get_file, email_finder_delete_file
• Bulk domain search: send_domain_search_file / _stream, status/get/delete
• List evaluator: send_list_evaluator_file / _stream, get_list_evaluator_result, send_evaluated_file
• Filters: add_filter, list_filters(use_post=...), delete_filter
• S3: list_s3files, validate_s3file, score_s3file, export_s3file on bulkapi root, as documented at https://www.zerobounce.net/docs/api-integrations/amazon-s3-bulk-api

Test plan

• pytest -k "email_finder or add_filter or list_evaluator" (docker)

Made with Cursor

Validate options, Inbox Placement Tester, list evaluator base URL

• validate: domain_info (website availability and WHOIS), greylist_processing, callback_url (requires greylist_processing=True). ZBValidateResponse reads domain_website_exists, domain_registrant_company_name, and message while a greylist retry is still running.
• Inbox Placement Tester: get_inbox_placement_providers, get_inbox_placement_test_types, create_inbox_placement_test, get_inbox_placement_test, list_inbox_placement_tests, delete_inbox_placement_test, get_inbox_placement_webhook, set_inbox_placement_webhook on https://bulkapi.zerobounce.net/api/ipt (base URL and path from the public docs). Arguments are checked before the request: name ≤ 64 characters, test type 1–3, sender_email for type 1, page_size 1–100.
• Base URLs: LIST_EVALUATOR_BASE_URL and INBOX_PLACEMENT_BASE_URL. The list evaluator lives at a different path on members-backend in test (/api/validation/list-evaluator/), so it can no longer be derived from BULK_BASE_URL. file_id is URL-encoded in the result path.
• Errors: a detail field (Django REST framework, used by the Inbox Placement Tester) raises ZBApiException with that text instead of raw JSON.
• Docs: README and documentation.md gain examples for the validate options, score_email, bulk finder and domain search, list evaluator, filters, the Inbox Placement Tester, and the per-API base URLs.

Test plan

• ruff check src tests, python -m compileall -q src tests, python -m pytest (80 passed): every new endpoint's method, host and path; JSON bodies in camelCase; optional fields omitted until set; invalid arguments send no request; detail errors are short.
• README examples run against the offline fake transport.
• Live check of the Inbox Placement Tester and the new validate options with a real key (not run).

S3 and SFTP/FTP bulk

Documented at https://www.zerobounce.net/docs/api-integrations/amazon-s3-bulk-api and https://www.zerobounce.net/docs/api-integrations/sftp_bulk_api.

• Added: email_finder_s3file, domain_search_s3file, validate_sftpfile, score_sftpfile, email_finder_sftpfile, domain_search_sftpfile, export_sftpfile, sending only the documented fields. has_header_row is required, as on the docs page. validate_sftpfile accepts file_name=None because the docs mark it optional for that endpoint only (likely a docs copy-paste; the other SFTP jobs require it).
• Fixed against the docs: list_s3files returns the files of the documented {"success": true, "files": [...]} response (it raised before); score_s3file sends return_url; export_s3file's export_bucket is optional.
• Aligned later in this PR: validate_s3file and score_s3file now take only the documented file_name, has_header_row (required), remove_duplicates and return_url (see below).
• 82 tests pass (every new endpoint's method/host/path, form fields, omitted optionals, client-side rejections, account errors, the documented listS3files shape). README examples run against the offline transport.

Docs audit fixes and edge tests

An endpoint-by-endpoint audit against https://www.zerobounce.net/docs/ found every documented endpoint covered except the Warmup API (added below), and no SDK method calling an undocumented endpoint.

• Bugs fixed: find_domain / guess_format raised KeyError on a lowercase message; an unknown confidence raised ValueError; mx_found: "false" (string, as in the docs' samples) read as true; processed_at without fractions and get_api_usage dates in the documented yyyy/mm/dd form raised ValueError; list evaluator uploads showed success=False on success (now ZBListEvaluatorResponse with the documented fields).
• Added: ai_agent_mailbox sub-status (RD-66, cherry-picked from the unpushed feature/ai-agent-mailbox-substatus); use_post=True on get_credits, get_api_usage, get_activity, find_email_format, find_domain; active_first_seen and two usage counts on the response models.
• Aligned with the docs: S3 jobs take only documented fields; bulk email finder needs a first-name or full-name column; find_email_format's first_name is optional; filter rule/target and Inbox Placement Tester names are checked before sending.
• Left as is (released behaviour): scoring_send_file keeps return_url optional and scoring_get_file keeps download_type, though the scoring docs mark the first required and don't list the second.
• Tests: new tests/test_offline_edges.py: the API key never appears in a transport error on any request path, error bodies (success: false, error_message, Cloudflare, 429, 500, detail), every optional upload field, argument checks, response-model edge cases, the POST variants. 105 tests pass; client coverage 84% → 93%. Every Python example in the README's new sections runs against the offline transport.

Warmup API (ZeroBounceWarmup)

Following https://www.zerobounce.net/docs/warmup-api: a separate client, because the Warmup API has its own team-scoped key, sent in the API-Key header, and its own host (https://warmup-api.zerobounce.net by default, or the base URL ZeroBounce provides).

• 26 methods, one per documented endpoint: sending accounts (list/get/add/update/delete, change from-address, list from-addresses), engagement (rules catalogue, set standard rule, custom rule get/create/update/delete), statistics and utilities (seeds, seed count, progress/sent today, emails per day, statistics, per-day, detailed, per-address, CSV downloads, DMARC check, SMTP test).
• Documented behaviour: 204 and empty 200 return None; CSV downloads return text and can save to a path; team_id is filled in where the schema needs it; check_domain_dmarc(domain) sends it as the documented from_address; custom-rule deletion sends a JSON body (query parameters return 422).
• Checked before sending: onboarding model, rule ids (0–4; 1–4 for the fallback), status ids (0–8), auto_enable required, custom percentages (reply 5–45, important 5–40, click 0–70 and ≤ important × 1.75), YYYY-MM-DD dates and their order, search_from characters, timezone_offset −11…14, email types, SMTP port.
• Errors: ZBApiException with a new status_code attribute (so callers can back off on 429, including the custom-rule cooldown); {"error"}, {"detail": "Not Found"} and 422 {"detail": [{"loc", "msg"}]} read as short messages; API key and SMTP password masked; redirects not followed.

Python 3.7–3.9

• ZeroBounce.__init__'s timeout: timedelta | None annotation made import zerobouncesdk raise TypeError on Python 3.7–3.9 (already on master and in 2.2.4; the package declares >=3.7). It is now Optional[timedelta], and the full suite passes on Python 3.9.6.

Tests

• New tests/test_warmup_offline.py: every endpoint's method, host, path and API-Key header (key never in the URL), request bodies and queries, documented successes (204, empty 200, integer, CSV), 29 invalid-argument cases that send nothing, every documented error status with status_code, redirects and HTML, secret masking. 113 tests pass on 3.12 and 3.9; zb_warmup.py coverage 98%. The README Warmup example runs offline.
• Not run: the live Warmup API (no Warmup key here).

Security review and dependency scan

Scans: osv-scanner and pip-audit on the resolved environments, bandit on src, an AST check of every requests call (all 7 set timeout and allow_redirects=False, none touches verify), and an independent review of the full diff. No high-severity findings.

• Fixed: redacted network errors kept the original exception, with the key in its URL or headers, as __context__; keys with whitespace or control characters leaked through the HTTP library's header error; Inbox Placement Tester sent the key in the URL (now the documented Authorization: Bearer header); non-https base URL attributes would have received the key; . / .. path IDs; SMTP credentials on some Warmup error paths; ruff unpinned in CI.
• Dependencies: requests >= 2.22.0 allowed versions with known advisories. Floors are now the oldest clean releases per Python version (requests / urllib3 / idna / certifi; test extra pytest). Python 3.12 resolves clean in osv-scanner and pip-audit. On Python 3.9 and older the fixed requests 2.33 and urllib3 2.7+ cannot be installed; the README now recommends 3.10+.
• Tests: tests/test_security_offline.py (7 tests). Reverting the __context__ or key-format fix makes them fail. 120 tests pass on 3.12 and 3.9.
• Follow-ups done in this PR (they were already on master): opt-in streamed downloads (stream=True); the publish workflow passes the tag through env; Dependabot auto-merge limited to patch/minor with majors left for review; a warning when an EU/US base_url meets the global bulk host. See the section below.
• Publishing: releases have always gone out through PyPI Trusted Publishing (the project trusts this repository's publish.yml in the release environment; the 2.2.4 run shows no password input and generated attestations). The publish step's password: ${{ secrets.PYPI_API_TOKEN }} referenced a secret that was never set, so it was dead configuration; it is removed and the setup is documented in README and AGENTS.md. Commit 380c50b's message wrongly says a token was replaced and should be revoked; there is none.

Downloads, regional hosts and workflows

• Streamed downloads: get_file, scoring_get_file, email_finder_get_file and domain_search_get_file take stream=True. The file is written in chunks to a .part file next to download_path and moved into place when complete; the first 64 KB are checked for an error body with the same rules as the buffered path. A dropped connection is redacted and leaves an existing file untouched. Default behaviour is unchanged.
• EU / US base URL: ZeroBounce documents no regional bulk host (and bulkapi-eu / bulkapi-us don't resolve), so bulk, scoring and finder files, list evaluator, S3/SFTP and Inbox Placement Tester calls go to bulkapi.zerobounce.net. The client now warns once per client when that happens with a regional base_url, unless the *_BASE_URL attributes were set.
• publish.yml: the tag input reaches the "Verify tag" and "Create release" scripts through env: TAG instead of ${{ }} expansion inside run:, which would execute a crafted value as shell.
• dependabot-auto-merge.yml: dependabot/fetch-metadata (pinned to v3.1.0's SHA) reads the update type. Patch and minor updates are approved and auto-merged when checks pass; a major update gets a comment and waits for a person. The weekly job only re-queues PRs the workflow already approved.
• 127 tests on Python 3.12 and 3.9 (7 new: every download method streams, error bodies and redirects leave no file, a dropped connection keeps the previous file and leaks no key, the regional warning appears once and not otherwise).

🤖 Generated with Claude Code