[franciscbalint]

Summary

• Add ZBValidateOptions (verify_plus, activity_data, timeout 3–60 / batch 10–120) on validate and validatebatch
• Map active_in_days and active_first_seen on ZBValidateResponse

Priority 2 — real-time /v2/scoring

• Add ZBScoreEmailResponse (email, score)
• scoreEmail — GET api_key + email query params on main apiBaseUrl
• scoreEmailPost — POST form-encoded api_key + email

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

• Bulk email finder / domain search (bulkapi /email-finder, /domain-search): sendfile, filestatus, getfile, deletefile (+ stream uploads)
• List evaluator: sendListEvaluatorFile, getListEvaluatorResult, sendEvaluatedFile
• Filters: addFilter, listFilters (GET or POST), deleteFilter
• S3: validateS3File, scoreS3File, exportS3File
• Options types: ZBEmailFinderSendFileOptions, ZBDomainSearchSendFileOptions, ZBValidateS3FileOptions, ZBScoreS3FileOptions

Test plan

• ./gradlew :zero_bounce_sdk:testDebugUnitTest --tests "com.zerobounce.android.ZeroBounceSDKTest.validateEmail*"
• ./gradlew :zero_bounce_sdk:testDebugUnitTest --tests "com.zerobounce.android.ZeroBounceSDKTest.scoreEmail*"
• ./gradlew :zero_bounce_sdk:testDebugUnitTest (includes P3: sendEmailFinderFile, validateS3File, addFilter)

Made with Cursor

---

Validate WHOIS and greylist options, Inbox Placement Tester, SFTP bulk

Ports 407f0a8 and b0444f8 from the Python SDK, on top of the work above. Everything is documented at https://www.zerobounce.net/docs/.

Added

• ZBValidateOptions gains domainInfo, greylistProcessing and callbackUrl. Booleans go on the wire as "true"/"false" on both the GET and the form POST. callbackUrl is where the greylist retry posts its result, so it is rejected without greylistProcessing, and when blank, before any request is sent.
• ZBValidateResponse reads domain_website_exists, domain_registrant_company_name and Message. Message is the API's Message key, returned instead of a result while a greylist retry is still running.
• emailFinderS3File, domainSearchS3File — https://www.zerobounce.net/docs/api-integrations/amazon-s3-bulk-api
• validateSFTPFile, scoreSFTPFile, emailFinderSFTPFile, domainSearchSFTPFile, exportSFTPFile — https://www.zerobounce.net/docs/api-integrations/sftp_bulk_api
• The Inbox Placement Tester. The API key goes on the query string, bodies are camelCase JSON, unset fields are left out, and it needs PUT and DELETE, so priority3JsonRequest builds the request itself rather than reusing the form-post helpers.
• setListEvaluatorBaseUrl and setInboxPlacementBaseUrl, with matching state on SdkState and wrappers on ZeroBounceClient.

Changed

• The list evaluator uses its own base URL instead of building the path from the bulk base. sendEvaluatedFile stays on the bulk base.
• exportS3File's exportBucket is nullable, matching the documented endpoint: null uses the export bucket from the account's settings. A blank string is still rejected.

Fixed — a real bug the new tests caught
A file id and an Inbox Placement test id are now encoded as a single path segment. Both went through enc(), which is URLEncoder form encoding and turns a space into + — correct in a query string, but a literal plus in a path. For the id a b/c the list evaluator was sending /v2/listevaluator/a+b%2Fc/. encPathSegment is new.

The two bulk shapes that are easy to get wrong

• validateSFTPFile's file_name is optional — leaving fileName null uses the input bucket from the account's settings. Every other job requires it, and a blank name is still rejected.
• exportSFTPFile sends export_path, not the export_bucket that exportS3File sends.

The SFTP server, path and protocol are never sent by the SDK; they come from the account's ZeroBounce settings.

Test plan

• ./gradlew :zero_bounce_sdk:testDebugUnitTest — 81 pass, up from 72 (9 new in OfflineApiTest)
• Offline only: a fake OkHttp interceptor records every call and answers without the network

🤖 Generated with Claude Code

---

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, verified against the live API

Brings this SDK level with the Python SDK's master, then checks every call against the real API. 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 a real defect, found by calling the endpoint:

• 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 — and its listing is GET /tests. GET /test answers Method "GET" not allowed, so listInboxPlacementTests had never worked.
• sendEvaluatedFile takes the list evaluator's file_id as a form field. A file upload is rejected with file_id: This field is required, so it now takes a file id rather than a File.
• The S3 and SFTP jobs require file_name and return_url — validateSFTPFile included, although the docs list file_name as optional for that one.

Two bugs the live run exposed in this SDK.

• Every fileStatus call failed. Bulk filestatus answers with an ISO-8601 upload_date (2026-10-24T05:24:13Z), and GsonDateDeserializer only knew yyyy-MM-dd HH:mm:ss.SSS and MM/dd/yyyy h:mm:ss a. The parse threw, the whole response was reported as an error, and the caller got the record's own field values as the error message. The deserializer now accepts the ISO-8601 forms too, and an offline test pins each one.
• {"success": false} on an HTTP 200 was returned as data. The API answers an unknown bulk file id that way. It now reaches the error callback, and ErrorResponse.statusCode carries the HTTP status 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 null, checkDomainDmarc 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 payload that is not a JSON object comes back as the JsonElement it is, because /seeds answers with an array and /seed-count with a bare number.

Testing. 117 offline tests pass (gradle :zero_bounce_sdk:testDebugUnitTest), no network. The live suite is excluded from the default test task unless -PzbLive is passed, so CI never runs it; the last full run with ZEROBOUNCE_LIVE_SPEND=1 ZEROBOUNCE_LIVE_CHANGES=1 was 40 passed, 0 failed, 4 skipped (the four skips are Warmup statistics endpoints, which need a sending account this team does not have). 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; the filter and sending account it does create are deleted in cleanup even when a check fails.

No version bump, tag or publish.

🤖 Generated with Claude Code