[franciscbalint]

Summary

• tests/live_api_test.py: an opt-in suite that calls every method of ZeroBounce and ZeroBounceWarmup against the real API. It is not collected by pytest, never runs in CI, and skips without keys.
  • Default (free): sandbox addresses, reads, and calls expected to fail (unknown file IDs, S3/SFTP without an integration) that still prove the API accepts the payload. Fails if the credit balance changed.
  • ZEROBOUNCE_LIVE_SPEND=1: scoring, activity, email finder, and full bulk round trips (upload, wait, buffered and streamed download, delete) for validation, scoring, email finder, domain search, and list evaluator + send_evaluated_file. Every job is deleted.
  • ZEROBOUNCE_LIVE_CHANGES=1: a test allowlist filter and a self-managed Warmup sending account (rename, rules, custom-rule cooldown, statistics), removed in cleanup even when a test fails.
  • Never: creating an Inbox Placement test, setting its webhook, or ZB-managed Warmup onboarding, because the API cannot undo them.
• README: how to run it, with keys and flags.
• AGENTS.md: every release needs a manual live run. Agents must tell the maintainer as early as possible which keys and flags it needs, must not tag until it passes, record the result, and never write a key anywhere.

Live result

2026-10-24, validation and Warmup keys, ZEROBOUNCE_LIVE_SPEND=1 and ZEROBOUNCE_LIVE_CHANGES=1: 20/20 passed. One test was adjusted during the run: a job created by send_evaluated_file answers "File cannot be found" for a short while after it is accepted, so the test waits through that.

Test plan

• ruff check, pytest (130 offline tests; the live file is not collected)
• Without keys: 20 skipped
• With both keys and both flags: 20 passed
• gitleaks on the branch: no keys committed

🤖 Generated with Claude Code