[franciscbalint]

Priority 2 — real-time AI scoring

• ScoreEmail (GET) and ScoreEmailPost (form POST) on /v2/scoring.
• Model: ZBScoreEmailResponse.

---

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, in its own partial class. The API key goes on the query string, bodies are camelCase JSON, unset fields are left out, and it needs PUT and DELETE, so it uses HttpClient.SendAsync directly rather than the existing helpers.
• SetListEvaluatorBaseUrl and SetInboxPlacementBaseUrl.

Changed

• The list evaluator uses its own base URL instead of building the path from the bulk base, and the file id is URL-encoded as one path segment. SendEvaluatedFile stays on the bulk base.
• ExportS3File's exportBucket is now optional, matching the documented endpoint: null uses the export bucket from the account's settings. A blank string is still rejected.

Fixed

• An error body whose JSON carries a detail string now surfaces that text. The Inbox Placement Tester is a Django REST framework app and reports its errors that way, unlike the error/message keys the rest of the API uses.

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.

Note on the encoding tests
Both percent-encoding assertions first failed against RecordedRequest.RawUri, which comes from Uri.ToString() and un-escapes %20 back to a space for display. The recorder now also keeps Uri.AbsoluteUri as EscapedUri, which is what goes on the wire; the %2F was correct all along.

Test plan

• dotnet test in the .NET 8 SDK image — 59 pass, up from 50 (9 new in OfflineApiTests)
• dotnet build on ZeroBounceSDK.csproj — 0 warnings, 0 errors
• Offline only: a fake HttpMessageHandler records every request 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 path or a stream.
• 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 failure callback.

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 JToken it is, because /seeds answers with an array and /seed-count with a bare number.

Status codes without changing the callbacks. The failure callbacks still take a string. ZBApiError, reachable as LastApiError on both clients, carries that same message with the HTTP status, so a caller can tell a Cloudflare 403 from an API 400/404 and a Warmup 429. It is set synchronously, just before the callback runs.

Testing. 94 offline tests pass (dotnet test), no network. The live suite is the ZeroBounceLiveApi project, which is not in the solution, so dotnet build and dotnet test never build or run 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