[franciscbalint]

Summary

• Add ZBValidateOptions overloads for validate / validateBatch
• Parse active_in_days / active_first_seen on ZBValidateResponse

Priority 2 — /v2/scoring (real-time AI scoring)

• scoreEmail (GET) and scoreEmailPost (form POST) on main API base URL
• ZBScoreEmailResponse (email, score)

Test plan

• ctest in build/ (53 tests passed)

Made with Cursor

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

• Priority3Options.h + Priority3.cpp: email finder / domain search, list evaluator, sendEvaluatedFile, filters, S3 validate/score/export
• Raw JSON callbacks for filter/list-evaluator GET responses

Test plan

• ctest — includes Tests.testValidateS3FileValid (53 tests)

---

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 query 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 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.
• setListEvaluatorBaseUrl / setInboxPlacementBaseUrl override those base URLs.
• BaseRequestHandler gains Put and Delete, used only by the Inbox Placement Tester. Both have default implementations, so any existing subclass keeps compiling.

Changed

• List evaluator uses its own base URL 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.
• An error body whose JSON carries error, message, error_message, or detail now reports that text rather than the whole JSON document.

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, the ZBS3ListFileEntry type, the option structs 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 take a new BulkFileJobOptions and build their form through one bulkFileJobFields 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, so BulkFileJobOptions::fileName is an optional — leaving it unset uses the input bucket from the account's settings. Every other job requires a name, and a blank one is still rejected.
• exportSFTPFile takes export_path, not the export_bucket that exportS3File sends. std::nullopt 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 and their options structs are untouched.

Tests: 88 pass, up from 77. Offline only — no live API calls. The offline recorder keeps the full URL and raw body so the tests can assert on path encoding and JSON shape.

---

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.
• 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 the parameter is now a file id, not a path.
• The S3 and SFTP jobs require file_name and return_url — validateSFTPFile included, although the docs list file_name as optional for that one.

A bug the live run exposed. {"success": false} on an HTTP 200 reached the success callback: the API answers an unknown bulk file id that way. It now goes to the error callback, and ZBErrorResponse::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 key with surrounding whitespace or control characters is refused before it can be quoted unredacted by the transport. BaseRequestHandler gains a Delete overload that carries a body, because the Warmup DELETE /custom-engagement needs one; it has a default implementation, so existing subclasses keep compiling.

Testing. 120 offline tests pass (ctest), no network. The live suite is its own executable, built only with -DZEROBOUNCE_BUILD_LIVE_TESTS=ON, so a normal build and CI never compile 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