[franciscbalint]

Docs: https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-validate-emails

Made with Cursor

---

Validate options, Inbox Placement Tester, list evaluator base URL

Ported from the Python SDK (407f0a8, a6710e5).

Added

• ZBValidateOptions gains domain_info, greylist_processing, callback_url. Booleans go on the wire as "true"/"false" on both the query and the form POST. callback_url is rejected without greylist_processing: Some(true), and when blank, before any request is sent.
• ZBValidation gains domain_website_exists, domain_registrant_company_name, and message (renamed from the API's Message key).
• Inbox Placement Tester in src/api/inbox_placement.rs on https://bulkapi.zerobounce.net/api/ipt: 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. API key on the query string, camelCase JSON bodies, unset fields omitted.
• ZBUrlProvider gains list_evaluator_url and inbox_placement_url, both overridable.

Changed

• List evaluator uses list_evaluator_url instead of building the path from the bulk base; the file id is URL-encoded as one path segment. send_evaluated_file stays on the bulk base.
• A greylist pickup still in progress returns no processed_at or free_email, so both now #[serde(default)] rather than failing the whole response.

Fixed

• An error body with a detail string (Django REST framework, used by the Inbox Placement Tester) returns that text.

S3 — removed, then restored

• An earlier push removed validate_s3_file, score_s3_file, export_s3_file, list_s3_files. That was wrong: they are documented, at https://www.zerobounce.net/docs/api-integrations/amazon-s3-bulk-api. All of them, the S3ListFileEntry struct, the post_bulk_root_form helper and the tests have been restored; only the parity work above remains.
• AGENTS.md keeps the "only documented endpoints" rule and now points at where the S3 docs live.
• Not added: emailFinderS3file and domainSearchS3file, and the SFTP variants on the Integrations index, are documented but have never been part of this SDK.

Notes

• reqwest's json() helper needs a feature this crate does not enable, so the JSON body and content type are set directly rather than widening the dependency. The path-segment encoder is a few lines in utility for the same reason.
• The offline test client now points list_evaluator_url and inbox_placement_url at the fake server. Without that the suite reached the live API — which is how the list evaluator test first failed.

New: the rest of the documented bulk surface

Seven endpoints that are documented but had never been in this SDK:

• email_finder_s3_file, domain_search_s3_file — https://www.zerobounce.net/docs/api-integrations/amazon-s3-bulk-api
• validate_sftp_file, score_sftp_file, email_finder_sftp_file, domain_search_sftp_file, export_sftp_file — https://www.zerobounce.net/docs/api-integrations/sftp_bulk_api

All six file jobs go through one bulk_root_file_job helper, which sends has_header_row and remove_duplicates as the strings true/false and omits remove_duplicates and return_url until they are set.

Two shapes differ from their S3 counterparts and are easy to get wrong:

• validate_sftp_file's file_name is optional, so it takes Option<&str> — None uses the input bucket from the account's settings. Every other job requires a name, and a blank one is still rejected.
• export_sftp_file takes export_path, not the export_bucket that export_s3_file uses. None uses the export path from those settings.

The SFTP server, path and protocol are never sent by the SDK; they come from the account's ZeroBounce settings. The existing S3 methods are untouched, so no caller signatures change.

Tests: 132 pass across the four suites; clippy reports no new warnings. Offline only — no live API calls.

---

RD-66: ai_agent_mailbox sub_status

Folded in from the former feature/ai-agent-mailbox-substatus branch, which has been deleted now that the commit lives here.

Adds the ai_agent_mailbox sub_status, which the API returns alongside both valid and catch-all. Tests cover both pairings, plus an unrecognised sub_status to pin that a value added to the API after this SDK ships degrades gracefully instead of failing the whole validate call.

No sub_status_ai_agent_mailbox usage counter was added: it is not documented.

---

Python-SDK parity, and the live API's actual behaviour

Brings this SDK level with the Python SDK's master. Where the live API and the docs disagree, the API wins and the call site says so.

What the live API taught us. Each of these was verified by calling the endpoint from the JavaScript, Go and PHP SDKs against the real API, and is fixed here too:

• validatebatch takes timeout as a JSON string. Sent as a number, the API rejects the whole batch with the account-level "Invalid API Key or your account ran out of credits" — which looks like a billing problem, not a payload one.
• The Inbox Placement Tester authenticates with Authorization: Bearer, not an api_key parameter. The key no longer reaches a query string that gets logged.
• send_evaluated_file takes the list evaluator's file_id as a form field. A file upload is rejected with file_id: This field is required, so the signature is now send_evaluated_file(file_id: &str).
• The S3 and SFTP jobs require file_name and return_url — validate_sftp_file included, although the docs list file_name as optional for that one. Both parameters are now &str rather than Option.

A bug the live runs exposed. {"success": false} on an HTTP 200 was returned as data: the API answers an unknown bulk file id that way, and two tests had pinned that wrong behaviour. It now raises, and ZBError::ApiError carries the HTTP status (ZBError::status_code()) so callers can tell a Cloudflare 403 from an API 400/404 and a Warmup 429.

New: the Warmup API client. ZeroBounceWarmup covers all 26 documented endpoints of what is a separate product — its own host, its own team-scoped key in an API-Key header, two CSV downloads. Ranges are checked before sending (engagement rules 0–4, reply 5–45 %, important 5–40 %, click ≤ 70 % and ≤ important × 1.75), 204 and empty 200 come back as Ok(None), check_domain_dmarc requires an email address (the live API rejects a bare domain), and the SMTP test masks the credentials out of every error it raises. A key with surrounding whitespace or control characters is refused before it can be quoted unredacted by the transport.

Testing. 162 offline tests pass (cargo test), no network.

The live suite ran green: 40 passed, 0 failed, 4 skipped. The four skips
are the per-address Warmup statistics; this team has no sending account. It
was run in a rust:1-bookworm container, which reaches both crates.io and the
API from this machine. An earlier revision of this description claimed the
suite could not be run here at all — that was wrong, and this replaces it.

A bug the live run found

get_api_usage always failed. The API returns only the counters that
apply to the account and the date range asked for, and an ordinary response
carries neither sub_status_gold nor sub_status_role_based_accept_all. Both
were required fields, so serde failed the whole response — surfaced as
"ZeroBounce returned a response that is not valid JSON", because the body is
over 1000 characters and carries no message or error key. Every counter on
ApiUsage now defaults to 0 when absent, so a counter the API adds or drops
later is ignored rather than fatal, and
sub_status_leading_period_removed / sub_status_alias_address, which the API
does return, are now read. The iOS SDK had the same bug from the same two
fields; it is fixed there too.

To run it yourself:

export ZEROBOUNCE_API_KEY=...
export ZEROBOUNCE_WARMUP_API_KEY=...
export ZEROBOUNCE_LIVE_SPEND=1 ZEROBOUNCE_LIVE_CHANGES=1
cargo test --features live --test live_api -- --nocapture

It is behind the live cargo feature, so cargo test and CI never compile it. Free calls run by default and assert the credit balance did not move; ZEROBOUNCE_LIVE_SPEND=1 adds the billable calls and a bulk round trip that deletes its own job, and ZEROBOUNCE_LIVE_CHANGES=1 adds a test filter and a self-managed Warmup sending account, both removed in cleanup even when a test fails. It never creates an Inbox Placement test, sets the Inbox Placement webhook, or starts ZB-managed Warmup onboarding, because the API cannot undo any of those.

No version bump, tag or publish.

🤖 Generated with Claude Code