[franciscbalint]

Priority 2 — real-time AI scoring

• scoreEmail (GET) and scoreEmailPost (form POST) on /v2/scoring.
• ZBScoreEmailResponse.

Priority 3 — bulk S3 / finder / filters

• listS3Files, validate/score S3, email finder, filters, list evaluator (see branch diff).

Polish (latest)

• PHPUnit testListS3FilesCallsBulkListS3files (mock lastRequestUrl + JSON array response).

Test plan

• testScoreEmail in PHPUnit suite
• testListS3FilesCallsBulkListS3files

---

Validate options, Inbox Placement Tester, list evaluator base URL

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

Added

• ZBValidateOptions gains domainInfo, greylistProcessing, callbackUrl. Booleans go on the wire as "true"/"false" on both the GET and the form POST. callbackUrl is rejected without greylistProcessing = true, and when blank, before any request is sent.
• ZBValidateResponse gains domainWebsiteExists, domainRegistrantCompanyName, and message (the API's Message key, returned while a greylist retry is still running).
• Inbox Placement Tester as its own trait (src/ZeroBounceInboxPlacement.php) on https://bulkapi.zerobounce.net/api/ipt: getInboxPlacementProviders, getInboxPlacementTestTypes, createInboxPlacementTest, getInboxPlacementTest, listInboxPlacementTests, deleteInboxPlacementTest, getInboxPlacementWebhook, setInboxPlacementWebhook. API key on the query string, camelCase JSON bodies, unset fields omitted.
• initialize takes optional third and fourth arguments to override the list evaluator and Inbox Placement Tester base URLs.

Changed

• List evaluator uses its own base URL (.../v2/listevaluator) instead of building the path from the bulk base; the file id is URL-encoded as one path segment. sendEvaluatedFile stays on the bulk base.

Fixed

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

S3 — removed, then restored

• An earlier push removed validateS3File, scoreS3File, exportS3File, listS3Files. That was wrong: they are documented, at https://www.zerobounce.net/docs/api-integrations/amazon-s3-bulk-api. All of them, their helpers, the BulkApiRootUrl constant 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.
  New: the rest of the documented bulk surface

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

• 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

All six file jobs go through one bulkRootFileJob 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:

• validateSFTPFile's file_name is optional — omitting it uses the input bucket from the account's settings. Every other job requires it.
• exportSFTPFile takes export_path, not the export_bucket that exportS3File uses. Omitting it 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.

Tests: 66 pass, 1 pre-existing skip. 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, 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 rather than by reading the docs:

• 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, and its listing is GET /tests. GET /test answers Method "GET" not allowed.
• 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.
• The S3 and SFTP jobs require return_url and file_name.
• The Warmup check-domain-dmarc takes an email address, not the domain the docs describe, and a failed SMTP login in test-smtp-configuration comes back as an HTTP 500.

Two bugs the live run exposed in this SDK.

• Every GET reported HTTP 0. The http:// stream wrapper reports its status only through PHP's predefined response-header variable, which the engine makes visible to the function that called file_get_contents and to no one else. The SDK read it from a helper, so it was always empty — an error status never reached the response check, and a 404 from the list evaluator came back as a successful result. Every verb now goes through cURL, which also removes the last read of the variable PHP 8.5 deprecates, so the legacy shim is gone and the guard test can assert the stronger property across all of src/.
• {"success": false} on an HTTP 200 was returned as data. The API answers an unknown bulk file id that way. It now raises, and ZBApiException::getStatusCode() carries the HTTP status so callers can tell a Cloudflare 403 from an API 400/404.

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, and the SMTP test masks the credentials out of every error it raises.

Also added

• $usePost on getCredits, getApiUsage, getActivity, scoreEmail, findEmail and findEmailFormat: the same parameters form-encoded, which keeps the key out of request logs.
• getApiUsage formats its dates. A DateTime was interpolated whole, so the request carried a locale-formatted timestamp that the API rejects and Cloudflare can block outright.
• ZBGetFileOptions::$stream for large result files: written in chunks to a temporary file beside the download path, moved into place only when complete, with the first 64 KB kept so an error body is still recognised rather than saved as a result.
• getListEvaluatorResult returns a typed ZBListEvaluatorResponse; everything the API sent is still on ->data.
• Safety: https-only base URLs and request URLs, keys with whitespace or control characters rejected before they can be quoted unredacted by the transport, . and .. refused as path ids, and a once-per-client warning when a regional base URL is paired with the single global bulk host.

Testing. 112 offline tests, 1046 assertions, no skips, no network. The live suite (composer run test:live) is excluded from composer test and from CI and needs keys from the environment; the last full run with ZEROBOUNCE_LIVE_SPEND=1 ZEROBOUNCE_LIVE_CHANGES=1 was 41 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 test fails. composer audit reports no advisories.

No version bump, tag or publish.

🤖 Generated with Claude Code