[franciscbalint]

Five calls whose signatures promised something the live API would not accept, plus two stale comments.

Fixed

scoreS3File could never succeed. ZBScoreS3FileOptions had no returnUrl field, so return_url was never sent, and the live API answers 400 {"error_message":"Provided return URL is not permitted: None"}. The field is added and required.

validateS3File's return_url was optional (options.returnUrl?.let) though the API requires it, so the same 400 was one default argument away.

Both now route through bulkRootFileJob, which already enforced file_name and return_url for the other six S3/SFTP jobs. All eight reject a missing field with the same message before a request goes out. The jobs keep their own extra fields (email_address_column, the name/gender/IP columns, allow_phase_2, remove_duplicate), and has_header_row is still omitted when unset on the two S3 jobs.

The bulk email finder accepted a file with no name column. Only domain_column >= 1 was checked; the docs require first_name_column or full_name_column alongside it. sendEmailFinderFile and sendEmailFinderFileStream now reject that call.

createInboxPlacementTest only rejected a blank name. It now checks the documented limits before spending a round trip on an endpoint that bills inbox-test credits: name at most 64 characters, testType in 1|2|3, and senderEmail required when testType == 1.

listInboxPlacementTests sent pageSize, which the API silently ignores (page_size=1 paginates; pageSize=1 returns the full list), so a caller asking for a small page quietly got everything. It now sends page_size, bounds it to 1-100, and gains the createdAfter / createdBefore filters, which were absent from ZBListInboxPlacementTestsOptions entirely.

setListEvaluatorBaseUrl redirected only half the List Evaluator. The result fetch used listEvaluatorBaseUrl, but the upload and send-evaluated-file were built from bulkApiBaseUrl, so overriding the host split one flow across two hosts. All three legs now follow the List Evaluator base; send-evaluated-file resolves one path segment above it, which leaves the default URLs unchanged.

Docs

• validateSFTPFile's KDoc told callers they could leave fileName null, but bulkRootFileJob errors with Empty parameter: file_name first. The code is right per the live API; the comment was stale.
• The Inbox Placement Tester block still claimed the API key goes on the query string. The code sends Authorization: Bearer.
• CHANGELOG, README and documentation.md updated; documentation.md also still carried both stale claims.

Public API

No names change. ZBScoreS3FileOptions.returnUrl and ZBListInboxPlacementTestsOptions.createdAfter / createdBefore are new fields with defaults, appended so existing positional construction keeps working. The new requirements surface through the error callback, matching how ZBBulkFileJobOptions already enforces its own.

Tests

Seven new offline tests and six updated ones, all against the repo's fake OkHttp transport (no network, no key): method, host, path, fields, auth placement, and the error bodies (success: false on a 200, the IPT detail key). ./gradlew :zero_bounce_sdk:testDebugUnitTest — 124 tests, 0 failures. ./gradlew :zero_bounce_sdk:assembleDebug — BUILD SUCCESSFUL.

The opt-in live suite (-PzbLive) was not run here; it needs real keys from the environment.

🤖 Generated with Claude Code