[franciscbalint]

Rebuilt on top of develop after PR #27 landed. That PR already brought the validate options, real-time AI scoring, the filters, the list evaluator and the first four S3 jobs — so this branch now adds only what is still missing, on develop's structure, rather than a second copy of that work.

Ports the rest of 407f0a8 and b0444f8 from the Python SDK. Everything is documented at https://www.zerobounce.net/docs/.

Validate options

validate accepts domain_info, greylist_processing and callback_url. An option left out is not sent, and booleans go on the wire as the strings "true"/"false".

callback_url is where the greylist retry posts its result, so it is rejected without greylist_processing, and when blank — before any request is sent.

The rest of the documented bulk surface

• email_finder_s3_file, domain_search_s3_file — https://www.zerobounce.net/docs/api-integrations/amazon-s3-bulk-api
• validate_sftp_file, score_sftp_file, email_finder_sftp_file, domain_search_sftp_file, export_sftp_file — https://www.zerobounce.net/docs/api-integrations/sftp_bulk_api

All six share bulk_root_file_job and go out through develop's existing bulk_root_form_post on the bulkapi root.

Two shapes differ from the rest and are easy to get wrong:

• validate_sftp_file's file name is optional — passing nil uses the input bucket from the account's settings. Every other job requires it.
• export_sftp_file sends export_path, not the export_bucket that export_s3_file sends.

The SFTP server, path and protocol are never sent by the SDK; they come from the account's ZeroBounce settings.

Inbox Placement Tester

The API key goes on the query string, bodies are camelCase JSON, and unset fields are left out. Spends the account's inbox-test credits.

Base URLs and plumbing

Configuration gains bulk_root_url, list_evaluator_root_url and inbox_placement_root_url. They are separate base URLs rather than paths built from bulk_api_root_url, so overriding that alone would leave a spec pointing at the live API. get_list_evaluator_result now uses the list evaluator's own base URL, encodes the file id as a single path segment, and rejects a blank id before a request.

BaseRequest gains __execute_with_method__ plus the public root_request and ipt_request: _get and _post could not express a form-encoded POST on an arbitrary base URL, or the Tester's PUT and DELETE. They live on BaseRequest so MockRequest inherits them too.

__parse_json_response__ now also raises on a detail key — the Tester is a Django REST framework app and reports its errors that way.

Test plan

• bundle exec rspec in the Ruby 3.2 image — 134 examples, 0 failures, up from 111 on develop
• Offline only: every request is stubbed with WebMock, and the argument-validation specs assert that no request was made at all

🤖 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 list_inbox_placement_tests had never worked.
• 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, so its argument is now a file id, not a path.
• The S3 and SFTP jobs require file_name and return_url — validate_sftp_file included, although the docs list file_name as optional for that one.

Two bugs the live run exposed in this SDK.

• Every filter write raised on success. /filters/add answers with a bare {"Message": "Filter successfully added"}, and a body that is nothing but Message is how the validate endpoints report a rejected request — so add_filter, delete_filter and list_filters turned a success into an error. The rule now skips the three filters paths, and two specs pin both halves of it.
• {"success": false} on an HTTP 200 was returned as data. The API answers an unknown bulk file id that way, and two specs had pinned that wrong behaviour. It now raises.

New: the Warmup API client. Zerobounce::Warmup 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 nil, check_domain_dmarc requires an email address (the live API rejects a bare domain), and the SMTP test masks the credentials out of every error it raises. Failures are Zerobounce::ApiResponseError, whose #status_code carries the HTTP status.

Testing. 173 offline specs pass (rspec), no network. The live suite (live/live_api.rb) sits outside spec/, so rspec and CI never load 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