[franciscbalint]

Summary

• Response size caps (F-01) for JSON and getfile downloads

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

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

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

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

Test plan

• ./build/bin/ZeroBounceTests (39 tests passed, incl. test_validate_s3_file_valid)

Made with Cursor

---

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.

---

Parity with the Python SDK, verified against the live API

Brings this SDK to the same surface as the (merged) Python SDK and checks every
call against the real API. Where the live API disagrees with the docs, the API
wins and the call site says so in a LIVE: comment.

A real bug the live run found

p3_append_form_field builds every form-encoded body. It starts from a NULL
buffer with a zero capacity and grows it with realloc, which for a NULL
pointer is malloc: the block comes back uninitialized. The code then took
strlen of it and strcat'ed onto it without terminating it first, so
whatever bytes the allocator happened to hand over were sent in front of the
first field.

It usually looked fine, because a fresh page is zeroed. Once the process had
allocated and freed enough, it was not — the live suite hit it as a Cloudflare
block (error 1020) on add_filter, and it affected send_evaluated_file and
the S3/SFTP file jobs just as much. Fixed, with an offline test pinning that
each of those bodies starts at api_key=.

Corrected against the live API

• 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" — an error that looks nothing like a bad field.
• The Inbox Placement Tester authenticates with Authorization: Bearer,
  not the api_key query parameter the rest of the API takes. As a parameter
  the request is rejected as unauthorized, and the key would end up in whatever
  logs the query string. Its listing is GET /tests (plural); /test answers
  Method "GET" not allowed.
• Every S3/SFTP job requires both file_name and return_url,
  validate_sftp_file included, although the docs call its file_name
  optional. Both are now checked before the request leaves.
• send_evaluated_file takes a file id as a form field, not a path to
  upload. Its second argument changed accordingly — the one breaking change
  here.
• A "success": false field on an HTTP 200 is a failure, not a result.
  get_file and delete_file report an unknown or deleted file id that way,
  so it now reaches the error callback. ZBErrorResponse.status_code carries
  the HTTP status so a caller can tell 429 from 500 without parsing the text.

Added

• ZeroBounceWarmup — a client for the Warmup API,
  a separate product with its own host, its own team-scoped key
  (zero_bounce_warmup_initialize, sent in an API-Key header) and all 26
  documented endpoints. Two more live findings are baked in:
  check-domain-dmarc takes an email address (a bare domain is answered
  "Please provide a valid email address"), and test-smtp-configuration
  answers a failed SMTP login with HTTP 500. The Warmup key and the SMTP
  credentials are redacted out of any error that escapes the client.
• Safety rails — a key with surrounding whitespace or control characters is
  rejected (it would otherwise be quoted unredacted in a transport error); only
  https:// URLs are called; a . or .. path id is rejected; redirects are
  never followed and only the https protocol is enabled; zb_redact_api_key
  strips the key out of any message built from a URL; and a regional base URL
  paired with the single global bulk host warns once.
• get_file_streaming / scoring_get_file_streaming write a result file
  straight to disk as it arrives rather than buffering it in memory. Opt-in,
  because a streamed body cannot be inspected as a whole: the first 4 KB are
  held back and checked, so a JSON or HTML error still reaches the error
  callback and no partial file is left behind.
• live/live_api.c, an opt-in live suite built only with
  -DZEROBOUNCE_BUILD_LIVE_TESTS=ON, so the default build and CI never compile
  it. Keys come from the environment only; ZEROBOUNCE_LIVE_SPEND=1 and
  ZEROBOUNCE_LIVE_CHANGES=1 opt in to calls that spend credits or make
  reversible account changes, and everything the changes tier creates is
  removed again in the same run. It never creates an Inbox Placement test, sets
  the Inbox Placement webhook, or starts ZB managed Warmup onboarding: the API
  cannot undo those.

Docs

README.md and documentation.md gain the Warmup API, the list evaluator and
the streaming download, and lose the two claims the live API contradicts.
AGENTS.md gains the live-API-wins rule, the safety rails, and a release rule:
run the live suite by hand with real keys before tagging, because the offline
suite cannot catch an API that has changed shape underneath the SDK.

Test plan

• cmake --build build + ./build/bin/ZeroBounceTests — 92 tests, 0 failures
• Live suite against the real API with both flags set —
  40 passed, 0 failed, 4 skipped (the four skips are the per-address
  Warmup statistics; this team has no sending account)
• Both also run on Linux in a container, since this machine's network
  policy blocks freshly built native binaries
• No key is written to a file, a commit, a log or a fixture; keys were
  passed as environment variables only

🤖 Generated with Claude Code