zerobounce-sdk 3.0.0 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +184 -17
- data/README.md +26 -13
- data/lib/zerobounce/api_key.rb +238 -7
- data/lib/zerobounce/api_urls.rb +53 -0
- data/lib/zerobounce/base_request.rb +199 -82
- data/lib/zerobounce/client.rb +12 -4
- data/lib/zerobounce/configuration.rb +19 -3
- data/lib/zerobounce/error.rb +19 -7
- data/lib/zerobounce/get_file_helper.rb +40 -27
- data/lib/zerobounce/http_transport.rb +229 -0
- data/lib/zerobounce/priority3.rb +187 -46
- data/lib/zerobounce/request.rb +25 -42
- data/lib/zerobounce/response_error.rb +27 -4
- data/lib/zerobounce/response_shape.rb +190 -0
- data/lib/zerobounce/strict_bool.rb +23 -0
- data/lib/zerobounce/strict_json.rb +165 -0
- data/lib/zerobounce/version.rb +1 -1
- data/lib/zerobounce/warmup.rb +155 -69
- data/lib/zerobounce.rb +138 -97
- metadata +5 -15
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 70be9be8449fa243c8c6f3a08a91a7a915f346a2cc1c211b5efd15f76ba3fa97
|
|
4
|
+
data.tar.gz: 6a64b2a7fc53e187a3924286a5d2e7832756e27c6df5c59bbb11fd05e3d346cb
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: d7ab782b46ee6e02efeefe634d9ca599f8e3ef371661400924334e528d72da0e06ddeaf5275392d39b5b53b197eca9e518f725dd9fbd0c43d3bf3dcc47f33068
|
|
7
|
+
data.tar.gz: eeac79cb8b78c59cf27d6f9fb9312dd4dd02c339109d23548013c3647ebe80b5c7ad74ef470c5a2d81e5afb73c651b13d3c13075c4df069176c8b9adf186be61
|
data/CHANGELOG.md
CHANGED
|
@@ -5,7 +5,98 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
-
## [3.
|
|
8
|
+
## [3.1.0] - 2026-11-15
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- Repository only: `gemfiles/ruby_3.0.gemfile.lock` is regenerated on Ruby 3.0 with Bundler 2.4.22 (as its Gemfile says): rest-client is gone, addressable is 2.9.2 (GHSA advisories fixed in 2.9.1), and public_suffix stays on 6.0.2, which Ruby 3.0 can install (7.x needs 3.2).
|
|
13
|
+
- **Behaviour change:** a body that is only message keys (`error`, `message`, `error_message`, `Message`, `Error`, `detail`; no `success`) and an empty `{}` are now an `ApiResponseError` with status 200 on every typed call (validate, validate_batch, credits, api_usage, activity, score_email, file send/status/delete for all three families, finder, domain search, send_evaluated_file, S3/SFTP jobs, list_s3_files, list-evaluator send). Before, only `guessformat` treated a message-only body as an error and `{}` was returned as a result. Unchanged: validate's greylist `{"Message": "..."}`, the filters calls, `get_list_evaluator_result`, all Inbox Placement calls, Warmup.
|
|
14
|
+
- **Behaviour change:** `validate_file_send` no longer sends `has_header_row` unless given (it defaulted to true and was always sent); `scoring_file_send` now defaults to `false` (as Java 3.1.0), was `true`.
|
|
15
|
+
- **Behaviour change:** `validate_batch` omits `ip_address` for rows without one (was `null`) and accepts `nil` for `ip_addresses`.
|
|
16
|
+
- **Behaviour change:** a `success` of `0`, `"0"`, `"false"` in any case is a failure.
|
|
17
|
+
- **Breaking:** the SDK no longer depends on rest-client; HTTP goes through Ruby's built-in `Net::HTTP` (no runtime dependency). An HTTP error status now raises `Zerobounce::ApiResponseError` with the status in `#status_code` (a `RuntimeError`), where up to 3.0.1 the validation client raised `RestClient::NotFound`, `RestClient::Forbidden` and so on (`#http_code`). Code that rescued `RestClient::ExceptionWithResponse` must rescue `ApiResponseError` (or `RuntimeError`). 3xx statuses are still not followed and raise with their status. Public method signatures are unchanged.
|
|
18
|
+
- Timeouts are explicit: open 30 s, read 120 s (write 120 s). Multipart uploads are built by the SDK; the file name is sent as raw UTF-8 with `"` as `%22` and CR/LF removed.
|
|
19
|
+
- Removed the `rest-client` gemspec dependency (and with it mime-types, http-cookie, netrc, domain_name, unf); regenerated `Gemfile.lock` and `gemfiles/ruby_3.0.gemfile.lock`; the `addressable` floor is now `>= 2.9.1` (the floor lockfile moves from 2.9.0 to 2.9.2, clearing its advisories).
|
|
20
|
+
- The README states the minimum Ruby (3.0, as the gemspec); CONTRIBUTING separates the development Ruby (3.4) from the supported floor. `.ruby-version` is 3.4.12 (was 3.2.1, end of life). The test image base is pinned by digest, and Dependabot keeps it current.
|
|
21
|
+
- The publish workflow checks the tag out by name in the test and publish jobs and stops unless it is the commit validate-tag checked; the tag input reaches shell steps only through env, publishes are serialised, and the RubyGems credentials step no longer names an API-token secret (publishing is trusted publishing only). The `release` environment is on the publishing job only.
|
|
22
|
+
|
|
23
|
+
### Removed
|
|
24
|
+
|
|
25
|
+
- `RESTCLIENT_LOG` / `RestClient.log` no longer apply; the SDK does no HTTP logging (it never enables `Net::HTTP` debug output). README says so.
|
|
26
|
+
|
|
27
|
+
### Fixed
|
|
28
|
+
|
|
29
|
+
- **Behaviour change:** a request is never re-sent by the HTTP layer. Before, Net::HTTP silently re-sent an idempotent GET/PUT/DELETE once after an EOF or reset (a billable `validate` could be charged twice); now `max_retries` is 0 and the failure raises `ApiResponseError` (status 0).
|
|
30
|
+
- A gzip body sent anyway must be a complete stream (a missing trailer is an error, status 0), and the decode error no longer carries the Zlib error as `#cause` (its message could quote the raw body, key included).
|
|
31
|
+
- A list-form `Content-Length` (`50, 50`) is checked like a single value; differing values are an error (status 0).
|
|
32
|
+
- **Behaviour change:** the Inbox Placement Tester calls other than `delete_inbox_placement_test` now raise `ApiResponseError` ("Empty response from ZeroBounce (HTTP 204)") on an empty 2xx body; before they returned nil as a success. DELETE still treats an empty 2xx as success.
|
|
33
|
+
- **Behaviour change:** `list_filters(use_post:)` is a strict boolean (`'false'` is false, `'junk'` raises); before any truthy value posted.
|
|
34
|
+
- **Behaviour change:** `add_filter` / `delete_filter` require non-blank Strings, `rule` of allow or block and `target` of email, domain, mx or tld (as the Python SDK).
|
|
35
|
+
- **Behaviour change:** the six Email Finder / Domain Search `*_file_status|get|delete` calls refuse a nil, blank or non-String `file_id` before sending.
|
|
36
|
+
- **Behaviour change:** every `*_column` (Email Finder, Domain Search, List Evaluator, including first/last/middle/full name columns) uses the integer-of-1-or-more check; `[1]`, `{}`, `1.5`, `'2x'` raise ArgumentError instead of NoMethodError or being sent.
|
|
37
|
+
- **Behaviour change:** Inbox Placement Tester: `list_inbox_placement_tests` requires Integer `page` >= 1 and `page_size` 1-100, `status` running/finished, strict YYYY-MM-DD `created_after`/`created_before`; `create_inbox_placement_test` requires a String name, Integer `test_type`, String `sender_email`, https `webhook_url`, Array ids/providers; unknown option keys raise ArgumentError (before they were dropped silently). `set_inbox_placement_webhook` requires an https URL.
|
|
38
|
+
- **Behaviour change:** the S3/SFTP file jobs raise on unknown option keys (e.g. `remove_duplicate`), and require a String `file_name` and an http(s) `return_url`; `export_s3_file` / `export_sftp_file` require a String `file_id`; `list_s3_files` rejects a non-String `bucket`/`search`.
|
|
39
|
+
- Warmup `statistics_per_day` checks dates strictly (2026-02-30 is refused); `from_address` and the other required values must be Strings; `add_sending_account` warns about an unknown top-level option.
|
|
40
|
+
- `api_usage` raises SDK messages ("Invalid parameter: start_date must be a date", "Empty parameter: ...") and refuses a start date after the end date, instead of the "strftime method not found" text.
|
|
41
|
+
- Message lists (`{"Message":["a","b"]}`, 400 `{"message":["x","y"]}`, `errors[].error` lists) are joined with a line break instead of showing the first entry; a non-string `error` is never shown as a Ruby inspect (lists joined, objects give "ZeroBounce returned an error with no message text.").
|
|
42
|
+
- Wrong argument types and nil/blank required values (`domain: 5`, `middle_name: 5`, `validate(nil)`, `activity(nil)`, `score_email(nil)`, file ids, `validate_batch(['a'], nil)`, `timeout: [1]`/`true`/`5.5`/`'abc'`, `send_stream(nil, nil)`, columns) raise the SDK's `ArgumentError` before anything is sent, with "Empty parameter: x" / "Invalid parameter: x ..." texts as in Python 3.1.0. `validate_batch` raises real messages instead of a bare "ArgumentError".
|
|
43
|
+
- `timeout` must be a whole number of seconds in range.
|
|
44
|
+
- `spec/mock_spec.rb` no longer reads `ZEROBOUNCE_API_KEY`; the seven `*-incorrect-api-key` cassettes (a Cloudflare 1020 block) are renamed `*-cloudflare-block`, and WebMock specs cover the API's real invalid-key answer.
|
|
45
|
+
- A gzip-encoded 200 cut short of its `Content-Length` read as a success on most calls (Net::HTTP decompresses and drops `Content-Length`). Requests now send `Accept-Encoding: identity`, the raw byte count is checked against `Content-Length`, and a short or chunked-then-cut body is an error with status 0 on every call, Warmup included.
|
|
46
|
+
- A refused connection raised a raw `Errno::ECONNREFUSED` and a cut chunked body `RestClient::ServerBrokeConnection`. Every transport failure (refused, reset, DNS, timeout, TLS, truncation) now raises `ApiResponseError` with `#status_code` 0 and a key-redacted message, on every call including Warmup.
|
|
47
|
+
- A file name containing a quote or CR/LF corrupted the multipart `Content-Disposition` header. Upload stream read failures (`*_send_stream`) raise `ApiResponseError` before anything is sent.
|
|
48
|
+
- **Behaviour change:** the four getfile downloads (`validate_file_get`, `scoring_file_get`, and their file-option variants) and Warmup `download_seeds` / `download_statistics` no longer return a JSON answer as file content. A body that, after an optional byte-order mark and white space, is any JSON object or array (`[1,2]`, `{"foo":1}`, BOM + `{"success":false,...}`) now raises `ApiResponseError` with the HTTP status; before, only objects with an error-shaped key were caught by getfile, and a BOM hid the JSON from both. A `Content-Type` of `application/json` or any `*/*+json` (`application/problem+json`) is an error whatever the body, where before only a type containing `application/json` was. The error carries the API's message, never the file content.
|
|
49
|
+
- `validate` and every `validate_batch` row require `address` and `status` as JSON strings, and each `validate_batch` row must be a JSON object: a 2xx result where either is missing, `null` or another JSON type raises `ApiResponseError` with `status_code` 200 ("ZeroBounce returned JSON of an unexpected shape: ..."). The greylist answer `{"Message": "..."}` is still returned as the result, and an unknown `status` string is kept. Up to 3.0.0 such a body was returned as the result. The other fields of these Hash results are passed through as sent.
|
|
50
|
+
- A 2xx body that is strict JSON but the wrong shape for the call (`0`, `"x"`, `null`, `true`, an array where an object is expected, an object where `list_filters` expects an array, an `errors` entry that is not an object) raises `ApiResponseError` with `status_code` 200 on every `Zerobounce` call. Up to 3.0.0 it was returned as the result, or raised a raw `TypeError` / `NoMethodError`. `list_s3_files` accepts a bare array or an object with a `files` array. `credits` raises the same error when `Credits` is missing, `null` or not an integer (`true`, `5.5`, `"abc"` or `"5.0"`); it returns the Integer for `Credits` sent as a JSON string (`"-1"`, `"12345"`, as the live API sends it) or as a JSON integer (`2375323`, as zerobounce.net's example shows). Up to 3.0.0 it returned 0 for a missing or non-numeric value, read `"5.0"` as 5 and raised `NoMethodError` for an array.
|
|
51
|
+
- A blank 2xx body (spaces, tabs or newlines only) on a `Zerobounce::Warmup` JSON call or an Inbox Placement call raises `ApiResponseError` with `status_code` 200: it is not JSON. Only a 204 or a 200 with no body at all is an empty success (`nil`). Up to 3.0.0 a blank body was returned as `nil` too.
|
|
52
|
+
- Every JSON call (the client, the raw-JSON, Inbox Placement and list evaluator calls, and `Zerobounce::Warmup`) parses a response body as strict RFC 8259 JSON: the body is checked first, untrimmed, by a small validator (`Zerobounce::StrictJson`; only space, tab, CR and LF may surround the value), then parsed with `allow_nan: false`. A body that is not strict JSON is an `ApiResponseError` with `status_code` 200. Up to 3.0.0 `JSON.parse` accepted `/* */` and `//` comments, and with some json versions other non-JSON (such as `\x41` escapes), so `/*c*/{"a":1}` on a 200 read as a success on 72 of 78 calls, Warmup included.
|
|
53
|
+
- `validate_file_send_stream` and `scoring_file_send_stream` work again. From 2.0.1 to 3.0.0 they raised `ArgumentError` ("File path must be under the current directory") whenever the system temp directory is outside the current directory, as it usually is: they wrote the content to a Tempfile in the system temp directory and uploaded its path, which the path check added in 2.0.1 rejects. 2.0.0 was not affected. The content is now uploaded from memory under the given `file_name` (2.0.0 sent the temp file's random name); file paths passed to `validate_file_send` and the other upload methods are still checked as before.
|
|
54
|
+
- A response whose body is cut short (the connection closes before `Content-Length` bytes arrive) raises `Zerobounce::ApiResponseError` with `status_code` 0 on every request, including the result-file downloads and `Zerobounce::Warmup`. Up to 3.0.0 Net::HTTP returned the bytes that had arrived, so a truncated result file or JSON body after a 200 header was returned as a success.
|
|
55
|
+
- `Zerobounce::Warmup#download_seeds` and `#download_statistics` raise `Zerobounce::ApiResponseError` (with the HTTP status) for a JSON object or array under a CSV content type (such as `text/csv` with `{"error": "..."}`). Up to 3.0.0 only a JSON content type was rejected, so that body was returned as the CSV text.
|
|
56
|
+
- `Zerobounce::Warmup#download_seeds` and `#download_statistics` raise `Zerobounce::ApiResponseError` (with the HTTP status) for an HTML page on a 200, such as a proxy's "Access denied" page, as the Python SDK does. Up to 3.0.0 the page was returned as the CSV text.
|
|
57
|
+
- An HTML page on a 200 (such as a proxy's "Access denied" page), or a JSON content type with a body that does not parse, raises `Zerobounce::ApiResponseError` with `status_code` 200 from every request method, as the Python and PHP SDKs do; so does any other non-JSON body from the calls that answer in JSON. Up to 3.0.0 `validate_file_send`, `scoring_file_send` (and their `_stream` forms), `send_email_finder_file`, `send_domain_search_file`, `email_finder_file_status`, `email_finder_file_delete`, `domain_search_file_status`, `domain_search_file_delete`, `send_list_evaluator_file`, `send_evaluated_file` and `list_s3_files` returned an HTML or other non-JSON body as a successful `String`; `validate_file_check`, `validate_file_delete`, `scoring_file_check` and `scoring_file_delete` raised a plain `RuntimeError` with no status for an HTML page, and `JSON::ParserError` for a JSON content type with a body that does not parse.
|
|
58
|
+
- Every `Zerobounce::Warmup` method that answers in JSON raises `Zerobounce::ApiResponseError` with `status_code` 200 for a `text/html` response, even when its body parses as JSON, as the client and the Python SDK do. Up to 3.0.0 such a body was returned as the result.
|
|
59
|
+
- `Zerobounce::Warmup#add_sending_account` parses `ignore_conflict` strictly, as the client parses its boolean options: `true`/`false`, `'true'`/`'false'` (any case) and `1`/`0` are accepted, and anything else raises `ArgumentError` before a request is sent. Up to 3.0.0 any truthy value was sent as `true`, so `ignore_conflict: 'false'` sent `true`. `ignore_conflict: nil` now leaves the field out (3.0.0 sent `false`).
|
|
60
|
+
- `Zerobounce::Warmup#add_sending_account` sends the documented ZeroBounce Managed fields: `email_content` takes `company_name`, `company_website`, `company_description`, `types_of_emails` and `example_email`, and `managed_sending` takes `weekdays_only`, `timezone`, `timezone_offset` and `warmup_start_date`, as the Python SDK and the API docs have them. Up to 3.0.0 it dropped `company_website`, `company_description`, `example_email`, `weekdays_only` and `timezone` without a word and sent `industry`, `website` and `daily_limit`, which the API does not read. The old `website` key is still accepted and sent as `company_website`; `industry`, `daily_limit` and any other unknown key are left out, as unknown keys always were, but now with a warning that names the documented fields. `weekdays_only` is parsed strictly (`'false'` is false; anything that is not a boolean raises `ArgumentError`), `timezone` must be a String, and `timezone_offset` takes fractional hours (-11 to 14, e.g. `3.0`), which 3.0.0 rejected; it must be an Integer or a finite Float (a String, `NaN` or `Infinity` raises `ArgumentError`).
|
|
61
|
+
- `Zerobounce::Warmup` raises `Zerobounce::ApiResponseError` with `status_code` 0 and a redacted message when a request times out (a read or open timeout). Up to 3.0.0 every Warmup method raised `NoMethodError` ("undefined method 'headers' for nil") instead.
|
|
62
|
+
- `validate_file_send` (and `validate_file_send_stream`) take `ip_address_column:` and `remove_duplicate:`, and `scoring_file_send` (and `scoring_file_send_stream`) take `remove_duplicate:`; each is sent only when given, `remove_duplicate` parsed strictly like the other booleans. Up to 3.0.0 neither documented field could be sent.
|
|
63
|
+
- **Behaviour change:** `validate_file_send` sends `first_name_column`, `last_name_column` and `gender_column` only when given, as the other SDKs do. Up to 3.0.0 it sent `first_name_column=2`, `last_name_column=3` and `gender_column=4` on every upload that did not set them, so any file with a second, third or fourth column had those mapped as first name, last name and gender. Pass them explicitly (`first_name_column: 2, last_name_column: 3, gender_column: 4`) to keep the old mapping. `email_address_column` (1) keeps its default; `has_header_row` is no longer sent by `validate_file_send` unless given (see above).
|
|
64
|
+
|
|
65
|
+
- Every documented field of every typed call has its JSON type checked, not only `Credits` and the `address` and `status` of `validate` and its batch rows. The calls are `validate`, `validate_batch` (each row and each `errors` entry), `api_usage`, `activity`, `score_email`, the file status, send and delete calls of every file family, `guessformat`, `find_domain`, `find_email` and the list evaluator. A field that arrives with another JSON type (such as `"score": "abc"`, `"email_batch": 5`, `"errors": 5`, `"processed_at": 5` or `"mx_found": 5`) raises `Zerobounce::ApiResponseError` with status 200, and `null` is accepted for every optional field. Up to 3.0.0 those fields were returned as results. The answers are still the Hashes the API sent.
|
|
66
|
+
|
|
67
|
+
- A finder or domain search body made only of message keys whose message is null, blank or not text raises `Zerobounce::ApiResponseError` with status 200 ("Request failed" when there is no text), as one with a text message already did. Up to 3.0.0 `{"message": null}` was returned as a result, and so was `{"message": ["..."]}`.
|
|
68
|
+
|
|
69
|
+
### Security
|
|
70
|
+
|
|
71
|
+
- Redaction is case-insensitive for non-ASCII letters (`É9` for `é9`) and the short-secret whole-token rule applies only at the secret's alphanumeric edges (`!ab` is masked in `key!ab`).
|
|
72
|
+
- **Behaviour change:** every base URL (`api_root_url`, `bulk_api_root_url`, `bulk_root_url`, `list_evaluator_root_url`, `inbox_placement_root_url`, the `ZEROBOUNCE_*_URL` variables, and `Warmup.new`'s `base_url`) is now parsed and refused with an `ArgumentError` at configuration unless it is an absolute https URL with a valid host and port, no userinfo, no whitespace/control/format characters and no backslash. Before, a prefix test let `https://api.zerobounce.net@evil.example/v2` send the API key to evil.example, and `https://exa mple.com` failed only at call time. The same check runs again on every send, including the bulk/S3 roots, the Inbox Placement Tester and Warmup.
|
|
73
|
+
- Redaction is case-insensitive (API key, Warmup key, SMTP password) in messages, `inspect` and `full_message`, and also decodes HTML entities (`d`, `d`, `'`, `"`) and backslash-escaped quotes (`\'`) before deciding that a text still holds a secret.
|
|
74
|
+
- **Behaviour change:** an API key is refused (`ArgumentError`, global config, `Client`, `with_api_key`, `Warmup`) if it holds whitespace of any kind, control or Unicode format characters anywhere ("api_key has whitespace, control or invisible characters"), or any non-ASCII ("api_key has characters that cannot be sent in an HTTP header"). Before, only surrounding ASCII whitespace and C0/DEL were refused.
|
|
75
|
+
- A secret shorter than 8 characters is masked only as a whole token (not touching a letter or digit), so an SMTP password `p` no longer turns "Failed to open" into "Failed to o***en". Secrets of 8 or more characters are masked wherever they occur.
|
|
76
|
+
- Confirmed: nothing in `lib` writes request lines (the RestClient log is gone with the Net::HTTP migration), and `ApiResponseError` carries only a redacted message and status, no response body or object.
|
|
77
|
+
- Redaction is closed under encoding. After the known spellings of the API key, the Warmup key and the SMTP username and password are masked, every error message is decoded up to four layers deep (the SDK's own request encoding plus three echo layers), in any order (URL-decoding, `+` as a space, JSON unescaping including `\/` and `\uXXXX`); if any decoded view still holds a secret, the message is replaced by "ZeroBounce returned an error; the response body was omitted because it contained a credential." (`Zerobounce::ApiKey::CREDENTIAL_OMITTED_MESSAGE`). Up to 3.0.0 a key URL-encoded twice (a server echoing a URL-encoded copy of a form body) came back unmasked, for example from `send_evaluated_file`, the filters and the S3/SFTP jobs.
|
|
78
|
+
- No error raised by the SDK carries the API key when a response body quotes it. Messages built from a body (a 2xx `{"error": "Invalid API key <key>"}`, a `{"success": false, "message": ...}`, a batch `"all"` error, an HTML page's title, a result-file download's JSON error) were passed on unredacted on every client method up to 3.0.0; only HTTP error statuses were redacted. `Zerobounce::ApiResponseError` now redacts its message itself (raw, URL-encoded and JSON-escaped forms), so every path that raises it is covered. A body that is not valid JSON no longer keeps the parser's error, which quotes the body, as `#cause` (client and `Zerobounce::Warmup`).
|
|
79
|
+
- `Zerobounce::Warmup` also masks the Warmup API key and the SMTP username and password of `test_smtp_configuration` in their JSON-escaped forms (`"` as `\"`, `/` as `\/`, non-ASCII as `\uXXXX`) and URL-encoded with `+` for spaces, in every error built from a response body, as the client now does for its key. Up to 3.0.0 only the raw and `%20`-encoded forms were masked, so a key or password containing `"` came back unmasked when a JSON body quoted it.
|
|
80
|
+
- The API key, the Warmup key and the SMTP username and password are also masked in the URL-encoded form of their JSON-escaped text (spaces as `+` and as `%20`, `/` as is or as `\/`, non-ASCII as is or as `\uXXXX`), which a server echoing a URL-encoded copy of a JSON request body returns, and JSON-escaped twice (a JSON error body quoting the JSON request body), on the client and on `Zerobounce::Warmup`. Up to 3.0.0 a secret containing `"`, `/` or `\` came back unmasked in those forms.
|
|
81
|
+
- `Zerobounce::Configuration`, `Zerobounce::Client` and `Zerobounce::Warmup` refuse `Marshal.dump` and `YAML.dump` (`to_yaml`): both raise `TypeError` without the key. Up to 3.0.0 the dump contained the API key in clear. `dup` and `clone` work as before.
|
|
82
|
+
- No error from `Zerobounce::Warmup` carries the Warmup API key or the SMTP credentials. Up to 3.0.0 every `ApiResponseError` raised for an HTTP error status kept the `RestClient` error as its `#cause`, whose `response.request` held the `API-Key` header (and, for `test_smtp_configuration`, the password in its payload). Errors are now raised with no cause.
|
|
83
|
+
- The client no longer re-raises `RestClient` errors for an HTTP error status. Up to 3.0.0 `RestClient::BadRequest` and the like carried the API key in `response.request` (the request URL or payload with `api_key`, and the underlying `Net::HTTP` response its URL). Every such status is now a `Zerobounce::ApiResponseError` with a redacted message, the status in `#status_code` and no cause, so there is no request object to leak.
|
|
84
|
+
|
|
85
|
+
- The API key is no longer an instance variable of `Zerobounce::Client` or `Zerobounce::Warmup` in plain text: it is held in a masked holder, so `instance_variables`, `instance_variable_get` and `pp` show `[FILTERED]`, as `inspect` already did. Up to 3.0.0 `@apikey` and `@api_key` held the key.
|
|
86
|
+
|
|
87
|
+
## [3.0.1] - 2026-11-12 (tagged, never published to RubyGems)
|
|
88
|
+
|
|
89
|
+
### Fixed
|
|
90
|
+
|
|
91
|
+
- `validate` without an IP address leaves `ip_address` out of the request. 3.0.0 sent a bare `ip_address` parameter with no value. An IP address that is given, including `'0'`, is still sent.
|
|
92
|
+
- `send_list_evaluator_file` uploads to `list_evaluator_root_url` (`ZEROBOUNCE_LIST_EVALUATOR_URL`), as `get_list_evaluator_result` already did. 3.0.0 posted to `bulk_api_root_url` + `listevaluator/` and ignored the setting. With the default URLs the request is unchanged (`https://bulkapi.zerobounce.net/v2/listevaluator/`).
|
|
93
|
+
- The S3 and SFTP/FTP jobs derive their root from `bulk_api_root_url` after dropping trailing slashes, so `bulk_api_root_url = 'https://host/v2//'` sends them to `https://host/listS3files` instead of `https://host/v2/listS3files`. A `bulk_root_url` that is set is used as before.
|
|
94
|
+
|
|
95
|
+
### Security
|
|
96
|
+
|
|
97
|
+
- A `Zerobounce::Warmup` transport error (for example a `SocketError`) no longer keeps the unredacted original error as `#cause`, which `#full_message` prints. Its own message was already redacted; the main client's errors already dropped the cause.
|
|
98
|
+
|
|
99
|
+
## [3.0.0] - 2026-11-11
|
|
9
100
|
|
|
10
101
|
### Breaking
|
|
11
102
|
|
|
@@ -30,7 +121,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
30
121
|
|
|
31
122
|
### Removed
|
|
32
123
|
|
|
33
|
-
- `Zerobounce::MockRequest` and the `TEST=unit` switch are gone. With `TEST=unit` set in the environment, the gem
|
|
124
|
+
- `Zerobounce::MockRequest` and the `TEST=unit` switch are gone. With `TEST=unit` set in the environment, the gem routed every call through `MockRequest`, which still called the API but skipped the newer response checks in `Request` (HTML pages, empty bodies, `"success": false`, message-only bodies), so an application's own test or CI setup could get different results from production. Nothing in the gem's specs used it.
|
|
34
125
|
|
|
35
126
|
## [2.2.0] - 2026-11-11
|
|
36
127
|
|
|
@@ -90,7 +181,13 @@ These change behaviour that 2.1.8 callers can rely on. Check each before upgradi
|
|
|
90
181
|
|
|
91
182
|
- `Gemfile.lock` matches the gemspec version, so a frozen install can resolve the gem.
|
|
92
183
|
|
|
93
|
-
## [2.1.
|
|
184
|
+
## [2.1.7] - 2026-06-17
|
|
185
|
+
|
|
186
|
+
### Changed
|
|
187
|
+
|
|
188
|
+
- First published release with the 2.1.6 `validate_batch` fix (2.1.6 was tagged but not published); `Gemfile.lock` bumped to the new version.
|
|
189
|
+
|
|
190
|
+
## [2.1.6] - 2026-06-17 (tagged, never published to RubyGems; shipped in 2.1.7)
|
|
94
191
|
|
|
95
192
|
### Fixed
|
|
96
193
|
|
|
@@ -102,7 +199,13 @@ These change behaviour that 2.1.8 callers can rely on. Check each before upgradi
|
|
|
102
199
|
|
|
103
200
|
- `catchall_domain` on validation results.
|
|
104
201
|
|
|
105
|
-
## [2.1.
|
|
202
|
+
## [2.1.4] - 2026-04-18
|
|
203
|
+
|
|
204
|
+
### Changed
|
|
205
|
+
|
|
206
|
+
- Development stack: tests run on Ruby 3.5+/4, VCR 6.4; `yard` raised for a Dependabot security advisory (the tagged, unpublished 2.1.2 and 2.1.3 hold the same line of work).
|
|
207
|
+
|
|
208
|
+
## [2.1.1] - 2026-04-09
|
|
106
209
|
|
|
107
210
|
### Security
|
|
108
211
|
|
|
@@ -114,25 +217,73 @@ These change behaviour that 2.1.8 callers can rely on. Check each before upgradi
|
|
|
114
217
|
|
|
115
218
|
- Optional bulk get-file parameters, including download type and activity data.
|
|
116
219
|
|
|
117
|
-
## [2.0.
|
|
220
|
+
## [2.0.13] - 2026-03-03
|
|
221
|
+
|
|
222
|
+
### Changed
|
|
223
|
+
|
|
224
|
+
- Version bump only (publish workflow checks; no library change from 2.0.12).
|
|
225
|
+
|
|
226
|
+
## [2.0.12] - 2026-03-03 (tagged, never published to RubyGems)
|
|
118
227
|
|
|
119
228
|
### Changed
|
|
120
229
|
|
|
121
230
|
- License the project under MIT.
|
|
122
231
|
|
|
123
|
-
## [2.0.1] - 2026-03-03
|
|
232
|
+
## [2.0.1] - 2026-03-03 (tagged, never published to RubyGems)
|
|
124
233
|
|
|
125
234
|
### Security
|
|
126
235
|
|
|
127
236
|
- Uploaded file paths must stay under the current directory.
|
|
128
237
|
|
|
129
|
-
## [2.0.0] - 2026-03-03
|
|
238
|
+
## [2.0.0] - 2026-03-03 (tagged, never published to RubyGems)
|
|
130
239
|
|
|
131
240
|
### Changed
|
|
132
241
|
|
|
133
242
|
- Release the 2.0 line of the gem.
|
|
134
243
|
|
|
135
|
-
## [1.
|
|
244
|
+
## [1.2.0] - 2025-10-22
|
|
245
|
+
|
|
246
|
+
### Changed
|
|
247
|
+
|
|
248
|
+
- Live tests fixed; version bump (the same day's 1.3.0 tag adds `find_email` and `find_domain`).
|
|
249
|
+
|
|
250
|
+
## [1.1.2] - 2025-08-28
|
|
251
|
+
|
|
252
|
+
### Changed
|
|
253
|
+
|
|
254
|
+
- Version bump only.
|
|
255
|
+
|
|
256
|
+
## [1.1.1] - 2024-02-06
|
|
257
|
+
|
|
258
|
+
### Changed
|
|
259
|
+
|
|
260
|
+
- Version bump only.
|
|
261
|
+
|
|
262
|
+
## [1.1.0] - 2023-09-04
|
|
263
|
+
|
|
264
|
+
### Added
|
|
265
|
+
|
|
266
|
+
- `guessformat` (email finder) and its live tests.
|
|
267
|
+
|
|
268
|
+
## [1.0.1] - 2023-05-13
|
|
269
|
+
|
|
270
|
+
### Added
|
|
271
|
+
|
|
272
|
+
- Activity data on `validate`.
|
|
273
|
+
|
|
274
|
+
## [1.0.0] - 2023-05-05
|
|
275
|
+
|
|
276
|
+
### Changed
|
|
277
|
+
|
|
278
|
+
- Gem renamed `zerobounce-sdk`; VCR-backed mock specs.
|
|
279
|
+
|
|
280
|
+
## [0.4.0] - 2023-05-05
|
|
281
|
+
|
|
282
|
+
### Changed
|
|
283
|
+
|
|
284
|
+
- Published to RubyGems; no matching commit in this repository (the next published version, 1.0.0, is the same day).
|
|
285
|
+
|
|
286
|
+
## [1.3.0] - 2025-10-22 (tagged, never published to RubyGems)
|
|
136
287
|
|
|
137
288
|
### Added
|
|
138
289
|
|
|
@@ -142,45 +293,61 @@ These change behaviour that 2.1.8 callers can rely on. Check each before upgradi
|
|
|
142
293
|
|
|
143
294
|
- `guessformat`. Use `find_email` or `find_domain`.
|
|
144
295
|
|
|
145
|
-
## [0.3.0] - 2023-09-18
|
|
296
|
+
## [0.3.0] - 2023-09-18 (never published to RubyGems)
|
|
146
297
|
|
|
147
298
|
### Changed
|
|
148
299
|
|
|
149
300
|
- Ruby and Bundler version requirements.
|
|
150
301
|
|
|
151
|
-
## [0.2.0] - 2023-09-12
|
|
302
|
+
## [0.2.0] - 2023-09-12 (never published to RubyGems)
|
|
152
303
|
|
|
153
304
|
### Changed
|
|
154
305
|
|
|
155
306
|
- Faraday requirements, and the minimum Ruby version is 2.5.
|
|
156
307
|
|
|
157
|
-
## [0.1.2] - 2023-04-18
|
|
308
|
+
## [0.1.2] - 2023-04-18 (never published to RubyGems)
|
|
158
309
|
|
|
159
310
|
### Fixed
|
|
160
311
|
|
|
161
312
|
- Error-body detection no longer depends on a quote immediately after the colon.
|
|
162
313
|
|
|
163
|
-
## [0.1.1] - 2023-04-12
|
|
314
|
+
## [0.1.1] - 2023-04-12 (never published to RubyGems)
|
|
164
315
|
|
|
165
316
|
### Fixed
|
|
166
317
|
|
|
167
318
|
- Removed safe-navigation calls so the client runs on older Ruby.
|
|
168
319
|
|
|
169
|
-
## [0.1.0] - 2023-04-07
|
|
320
|
+
## [0.1.0] - 2023-04-07 (never published to RubyGems)
|
|
170
321
|
|
|
171
322
|
### Added
|
|
172
323
|
|
|
173
324
|
- Initial client for ZeroBounce API v2.
|
|
174
325
|
|
|
175
|
-
[
|
|
326
|
+
[3.1.0]: https://github.com/zerobounce/zero-bounce-ruby/compare/v3.0.0...v3.1.0
|
|
327
|
+
[3.0.1]: https://github.com/zerobounce/zero-bounce-ruby/compare/v3.0.0...v3.0.1
|
|
176
328
|
[3.0.0]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.2.0...v3.0.0
|
|
177
329
|
[2.2.0]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.8...v2.2.0
|
|
178
|
-
[2.1.8]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.
|
|
330
|
+
[2.1.8]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.7...v2.1.8
|
|
331
|
+
[2.1.7]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.6...v2.1.7
|
|
179
332
|
[2.1.6]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.5...v2.1.6
|
|
180
|
-
[2.1.5]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.
|
|
333
|
+
[2.1.5]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.4...v2.1.5
|
|
334
|
+
[2.1.4]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.1...v2.1.4
|
|
181
335
|
[2.1.1]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.0...v2.1.1
|
|
182
|
-
[2.1.0]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.0.
|
|
336
|
+
[2.1.0]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.0.13...v2.1.0
|
|
337
|
+
[2.0.13]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.0.12...v2.0.13
|
|
183
338
|
[2.0.12]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.0.1...v2.0.12
|
|
184
339
|
[2.0.1]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.0.0...v2.0.1
|
|
185
340
|
[2.0.0]: https://github.com/zerobounce/zero-bounce-ruby/compare/v1.3.0...v2.0.0
|
|
186
341
|
[1.3.0]: https://github.com/zerobounce/zero-bounce-ruby/releases/tag/v1.3.0
|
|
342
|
+
[1.2.0]: https://github.com/zerobounce/zero-bounce-ruby/commit/28fcc43
|
|
343
|
+
[1.1.2]: https://github.com/zerobounce/zero-bounce-ruby/releases/tag/v1.1.2
|
|
344
|
+
[1.1.1]: https://github.com/zerobounce/zero-bounce-ruby/commit/ee18dc5
|
|
345
|
+
[1.1.0]: https://github.com/zerobounce/zero-bounce-ruby/commit/26b463f
|
|
346
|
+
[1.0.1]: https://github.com/zerobounce/zero-bounce-ruby/commit/0d1b29e
|
|
347
|
+
[1.0.0]: https://github.com/zerobounce/zero-bounce-ruby/commit/5ed7d51
|
|
348
|
+
[0.4.0]: https://rubygems.org/gems/zerobounce-sdk/versions/0.4.0
|
|
349
|
+
[0.3.0]: https://github.com/zerobounce/zero-bounce-ruby/commit/86ccabe
|
|
350
|
+
[0.2.0]: https://github.com/zerobounce/zero-bounce-ruby/commits/f143791
|
|
351
|
+
[0.1.2]: https://github.com/zerobounce/zero-bounce-ruby/commits/f143791
|
|
352
|
+
[0.1.1]: https://github.com/zerobounce/zero-bounce-ruby/commits/f143791
|
|
353
|
+
[0.1.0]: https://github.com/zerobounce/zero-bounce-ruby/commits/f143791
|
data/README.md
CHANGED
|
@@ -2,6 +2,10 @@
|
|
|
2
2
|
# Zerobounce
|
|
3
3
|
Ruby client for Zerobounce.net API. Developed based on [this version](https://github.com/afrase/zerobounce) by Aaron Frase.
|
|
4
4
|
|
|
5
|
+
## Requirements
|
|
6
|
+
|
|
7
|
+
Ruby 3.0 or newer (`required_ruby_version >= 3.0` in the gemspec).
|
|
8
|
+
|
|
5
9
|
|
|
6
10
|
## Security
|
|
7
11
|
|
|
@@ -405,11 +409,13 @@ Zerobounce.validate_file_send(validate_file_path)
|
|
|
405
409
|
# "file_id"=>"75d854a6-565c-49f9-b4c8-b3344480ec4c"}
|
|
406
410
|
# file_id will be required for next steps
|
|
407
411
|
# optional named parameters:
|
|
408
|
-
# email_address_column: 1,
|
|
409
|
-
# first_name_column: 2,
|
|
412
|
+
# email_address_column: 1, # the default
|
|
413
|
+
# first_name_column: 2, # this and the columns below are sent only when given
|
|
410
414
|
# last_name_column: 3,
|
|
411
415
|
# gender_column: 4,
|
|
412
|
-
#
|
|
416
|
+
# ip_address_column: 5,
|
|
417
|
+
# has_header_row: true, # sent only when given (no default)
|
|
418
|
+
# remove_duplicate: false, # sent only when given; the API removes duplicates by default
|
|
413
419
|
# return_url: nil, # results callback url
|
|
414
420
|
# allow_phase_2: true # optional; validation bulk sendfile only (omit or nil to skip)
|
|
415
421
|
Zerobounce.validate_file_send(validate_file_path, email_address_column: 1, gender_column: 4)
|
|
@@ -478,7 +484,8 @@ Zerobounce.scoring_file_send(scoring_file_path)
|
|
|
478
484
|
# file_id will be required for the next steps
|
|
479
485
|
# optional named parameters
|
|
480
486
|
# email_address_column: 1,
|
|
481
|
-
# has_header_row: true
|
|
487
|
+
# has_header_row: false, # the default; pass true if the file has a header row
|
|
488
|
+
# remove_duplicate: false, # sent only when given
|
|
482
489
|
# return_url: nil # results callback url
|
|
483
490
|
Zerobounce.scoring_file_send(scoring_file_path, email_address_column: 1)
|
|
484
491
|
```
|
|
@@ -699,11 +706,12 @@ Zerobounce.find_domain(company_name: "Zero Bounce")
|
|
|
699
706
|
|
|
700
707
|
## Errors
|
|
701
708
|
|
|
702
|
-
- An HTTP error status raises
|
|
709
|
+
- An HTTP error status raises `Zerobounce::ApiResponseError` (a `RuntimeError`) with that status in `#status_code`. The message is the API's own short error text; an HTML error page is reduced to its title. **Behaviour change:** up to 3.0.1 the validation client raised `RestClient::NotFound`, `RestClient::Forbidden` and so on (`#http_code`); the SDK no longer depends on rest-client, so those classes are gone.
|
|
710
|
+
- A transport failure - connection refused or reset, DNS, a read or open timeout (open 30 s, read 120 s), a TLS error, or a response body shorter than its `Content-Length` or a chunked body cut off - raises `Zerobounce::ApiResponseError` with `#status_code` 0 and a message with the API key removed, on every call including Warmup. Responses are requested uncompressed (`Accept-Encoding: identity`) so a body cut short is always detected.
|
|
703
711
|
- An error reported with an HTTP 200 - an `error` field, an `Error` or `error_message` field without `success`, `{"success": false}`, or an account-level `validate_batch` failure - raises `Zerobounce::ApiResponseError` (a `RuntimeError`) with the API's message; `#status_code` is the HTTP status, usually 200. `find_email`, `find_domain` and `guessformat` also raise for a body made only of message fields (such as `{"Message": "Invalid API key or your account ran out of credits"}`).
|
|
704
712
|
- `validate`'s greylist answer, `{"Message": "Greylist validation still in progress..."}`, is a result: the Hash is returned with its `Message`.
|
|
705
713
|
- Invalid arguments, a boolean option that is not `true`/`false`, `'true'`/`'false'` or `1`/`0`, an API key with surrounding whitespace or control characters, and a base URL that is not `https://` raise `ArgumentError` before any request is sent.
|
|
706
|
-
- Redirects are not followed; a 3xx raises
|
|
714
|
+
- Redirects are not followed; a 3xx raises `Zerobounce::ApiResponseError` with its status.
|
|
707
715
|
- The Warmup client raises `Zerobounce::ApiResponseError`, whose `#status_code` gives the HTTP status.
|
|
708
716
|
|
|
709
717
|
The API key is removed from every error message.
|
|
@@ -711,14 +719,14 @@ The API key is removed from every error message.
|
|
|
711
719
|
```ruby
|
|
712
720
|
begin
|
|
713
721
|
Zerobounce.validate_file_check("00000000-0000-0000-0000-000000000000")
|
|
714
|
-
rescue
|
|
715
|
-
e.
|
|
716
|
-
e.message
|
|
717
|
-
rescue RuntimeError => e
|
|
718
|
-
e.message # => e.g. "File cannot be found."
|
|
722
|
+
rescue Zerobounce::ApiResponseError => e
|
|
723
|
+
e.status_code # => 404 for an HTTP status, 200 for an error on a 200, 0 for a transport failure
|
|
724
|
+
e.message # => the API's error text, e.g. "File cannot be found."
|
|
719
725
|
end
|
|
720
726
|
```
|
|
721
727
|
|
|
728
|
+
The SDK uses Ruby's built-in `Net::HTTP` and does no HTTP logging: it never turns on `Net::HTTP`'s debug output, and the `RESTCLIENT_LOG` environment variable has no effect.
|
|
729
|
+
|
|
722
730
|
## Warmup API
|
|
723
731
|
|
|
724
732
|
The Warmup API is a separate product. It has its own host, its own team-scoped key, and its own client; your validation key will not work with it.
|
|
@@ -742,11 +750,16 @@ Or have ZeroBounce provision the mailbox. A 200 means the request was accepted;
|
|
|
742
750
|
```ruby
|
|
743
751
|
warmup.add_sending_account(
|
|
744
752
|
'sender@example.com', 'zb_managed',
|
|
745
|
-
email_content: {
|
|
746
|
-
|
|
753
|
+
email_content: { company_name: 'Acme', company_website: 'https://acme.example',
|
|
754
|
+
company_description: 'B2B email tools', types_of_emails: %w[newsletter marketing],
|
|
755
|
+
example_email: 'Hi, a short intro to Acme.' },
|
|
756
|
+
managed_sending: { weekdays_only: true, timezone: 'America/New_York', timezone_offset: -5,
|
|
757
|
+
warmup_start_date: Date.new(2026, 3, 4) }
|
|
747
758
|
)
|
|
748
759
|
```
|
|
749
760
|
|
|
761
|
+
Keys other than these are not API fields: they are left out of the request with a warning.
|
|
762
|
+
|
|
750
763
|
A custom engagement rule can be changed only once every seven days; inside that window the API answers 429.
|
|
751
764
|
|
|
752
765
|
```ruby
|