[franciscbalint]

Summary

Every SDK method was called against the live API: the validation-API client and ZeroBounceWarmup, every endpoint, successful or not, to check field names, types and response shapes. Where the live API and the docs disagree, the SDK now follows the API.

Fixed

Method	Live API behaviour	Change
validate_batch(timeout=…)	A JSON number makes the API reject the whole batch with "Invalid API Key or your account ran out of credits"; a string works	timeout is sent as a string
send_evaluated_file	Rejects an upload ("file_id: This field is required"); the evaluator's file_id starts a validation job	send_evaluated_file(file_id)
S3 / SFTP jobs	Without return_url: "Provided return URL is not permitted: None"; validateSFTPfile without file_name: "This field is required"	Both required, checked before sending
check_domain_dmarc	A bare domain: "Please provide a valid email address"	Takes an email address
Inbox Placement Tester errors	Body is a JSON list (["In-progress tests cannot be deleted."])	Read as its first message
Main client errors	—	ZBApiException.status_code set (403 Cloudflare, 400/404 API)

Verified live (no change needed)

• Validation, every validate option (GET and POST), batch, credits, usage, activity, scoring, email finder, domain search, guess_format, filters (add → visible after propagation → delete → "does not exist").
• Bulk round trips (send, buffered and streamed upload, status, buffered and streamed download, delete) for validation, scoring, email finder and domain search; list evaluator (file and stream).
• Inbox Placement Tester with the Bearer header: providers, test types, create (Auto Alias and Email), get, list with filters, delete (running test refused), webhook get/set.
• All 26 Warmup endpoints with a Warmup key, including the 7-day custom-rule cooldown (429), 204 / empty successes, CSV downloads; the test sending account was deleted afterwards.
• S3 / SFTP: with the required fields every job passes payload validation and stops at the account's missing AWS / SFTP setup, so the jobs themselves are untested.

API issues to report (not SDK bugs)

• Warmup test-smtp-configuration returns HTTP 500 for any failed SMTP login (documented as a failure message).
• The docs for send-evaluated-file, S3/SFTP return_url, validateSFTPfile file_name, check-domain-dmarc and validatebatch timeout describe what the API rejects.
• Cloudflare returns 403 "Access denied" for some malformed file_id values on bulkapi instead of an API error.

Test plan

• ruff check, compileall, pytest — 130 passed on Python 3.12 and 3.9
• Every example in README.md (32) and documentation.md (31) runs against the offline fakes
• Each fix re-verified against the live API

🤖 Generated with Claude Code