zerobounce-sdk 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6af251b375110bd15d24b7f59f9cf4825e698a7e2009b0b7c4ed4a55c385dc7f
-  data.tar.gz: 630b6eda82fc8c016cf6cfb76fc54ff44db9aca843b8e9042f96c454083472cb
+  metadata.gz: a38febb2edd021c081aefb3df14db686a54ef1f41142f6559fd95069ad97219c
+  data.tar.gz: 13f9d5846f1ba7ac10c4afb082197f4d7b0efcbfa3bee2bb25310b82f27b2979
 SHA512:
-  metadata.gz: e7f27766cddc52f625cd1fa3f7fa8902c252711d81aec0d28cbc39b4fc32548fec550f753655f3f0ffab2ef19aa2f75e1bd186d9a908afbe20d65e7dfd3c2f9b
-  data.tar.gz: 986f86e4b3a9592d6f30f3a32be9a85e9d7a7e55029aac88d2ae72f9894eb60550f3a9028870e6dd31b515efc09c212e5fc7cf0f38c01ba2c98db4b37ac16686
+  metadata.gz: 4d0c27a41276b918ba70daa8e62dc9b7bff1fe4f067ffe5119b33cd1ab891b0249a3f83eb53cc6fa237388de13a47e7edce9c3ade36f38a85dde9031f741fdef
+  data.tar.gz: 4b7c4ba9febcbf1a45d5b1f8028d35ac6128d374c827973130aa7e040992df988ab6c36ecd13a6974ba7c170d2ee30a4df0967af541baccff8ceebeeb2e5a8fe

data/CHANGELOG.md

@@ -5,7 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [3.0.0] - 2026-11-12
+
+### Breaking
+
+- **Breaking:** boolean options are parsed strictly. `true`/`false`, `'true'`/`'false'` (any case) and `1`/`0` are accepted; anything else raises `ArgumentError` naming the option before a request is sent. Up to 2.2.0 any truthy value was sent as `true`, so `activity_data: 'false'` sent `true`. Affects `validate` (`activity_data`, `verify_plus`, `domain_info`, `greylist_processing`), `validate_batch`, `validate_file_send`/`scoring_file_send` (`has_header_row`, `allow_phase_2`), `GetFileOptions#activity_data`, `send_email_finder_file`, `send_domain_search_file`, and the S3/SFTP jobs (`has_header_row`, `remove_duplicates`); a `nil` `has_header_row` on an S3/SFTP job, which 2.2.0 sent as `false`, now raises.
+- **Breaking:** an API key with surrounding whitespace or control characters (for example one read from a file with its newline) raises `ArgumentError` before any request, from `Zerobounce.configure`'s key, `Zerobounce.with_api_key` and `Zerobounce::Client.new`, as `Zerobounce::Warmup.new` already did. 2.2.0 sent it as it was.
+
+### Fixed
+
+- `validate` returns the greylist answer `{"Message": "Greylist validation still in progress..."}` as its result (GET and `use_post: true`). 2.2.0 raised `RuntimeError` for it, so `greylist_processing: true` could never be used to pick up a result later.
+- A 2xx `{"error_message": "..."}` with no `success` field raises. 2.2.0 returned it as the result, and `credits` returned `0` for it.
+- `find_email`, `find_domain` and `guessformat` raise for a body made only of message fields (`detail`, `error_message`, `message`, as well as `Message`); 2.2.0 returned `{"detail": ...}` and `{"error_message": ...}` as results.
+- `validate_file_get`, `scoring_file_get` and the email finder and domain search downloads raise `Empty response from ZeroBounce (HTTP 200)` for an empty body instead of returning `""`.
+- `validate_file_check`, `validate_file_delete` and the scoring equivalents no longer raise an empty message for `{"error": ""}`; an empty `error` is not an error.
+- `Zerobounce::Client#inspect` and `Zerobounce::Warmup#inspect` no longer show the API key.
+
+### Changed
+
+- Errors reported on a 2xx response raise `Zerobounce::ApiResponseError` with `#status_code` set to the HTTP status (usually 200). `ApiResponseError` is now a subclass of `RuntimeError` (it was a `StandardError`), so `rescue RuntimeError` catches these errors as before.
+- The license file is named `LICENSE` (it was `LICENSE.txt`), and the gem ships only that one license file.
+- The gemspec has a fuller summary and description, and `source_code_uri`, `changelog_uri` and `homepage_uri` metadata.
+- Development only (nothing ships to gem users): `benchmark` is a development dependency, because it left Ruby 4.0's default gems and RuboCop needs it.
+
+### Removed
+
+- `Zerobounce::MockRequest` and the `TEST=unit` switch are gone. With `TEST=unit` set in the environment, the gem answered every call with canned responses instead of calling the API, which could silently fake results in an application's own test or CI setup. Nothing in the gem's specs used it.
 
 ## [2.2.0] - 2026-11-11
 
@@ -147,7 +172,8 @@ These change behaviour that 2.1.8 callers can rely on. Check each before upgradi
 
 - Initial client for ZeroBounce API v2.
 
-[Unreleased]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.2.0...HEAD
+[Unreleased]: https://github.com/zerobounce/zero-bounce-ruby/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.2.0...v3.0.0
 [2.2.0]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.8...v2.2.0
 [2.1.8]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.6...v2.1.8
 [2.1.6]: https://github.com/zerobounce/zero-bounce-ruby/compare/v2.1.5...v2.1.6

data/README.md

@@ -700,8 +700,9 @@ Zerobounce.find_domain(company_name: "Zero Bounce")
 ## Errors
 
 - An HTTP error status raises the `RestClient` exception for that status, as it did up to 2.1.8: `RestClient::NotFound`, `RestClient::Forbidden` and so on, all subclasses of `RestClient::ExceptionWithResponse` and of `RuntimeError`. `#http_code` gives the status. The message is the API's own short error text (up to 2.1.8 it was RestClient's, such as `404 Not Found`); an HTML error page is reduced to its title.
-- An error reported with an HTTP 200 - an `error` field, `{"success": false}`, or an account-level `validate_batch` failure - raises `RuntimeError` with the API's message.
-- Invalid arguments, and a base URL that is not `https://`, raise `ArgumentError` before any request is sent.
+- 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"}`).
+- `validate`'s greylist answer, `{"Message": "Greylist validation still in progress..."}`, is a result: the Hash is returned with its `Message`.
+- 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.
 - Redirects are not followed; a 3xx raises its `RestClient` exception (for example `RestClient::Found`).
 - The Warmup client raises `Zerobounce::ApiResponseError`, whose `#status_code` gives the HTTP status.
 
@@ -839,3 +840,7 @@ Run it by hand before every release: the offline suite proves the SDK sends what
 2. **Actions → Publish → Run workflow** with that tag.
 
 Registry: [zerobounce-sdk on RubyGems](https://rubygems.org/gems/zerobounce-sdk)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/zerobounce/api_key.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  # Checks an API key before it is sent.
+  module ApiKey
+    module_function
+
+    # The key, unchanged, or an ArgumentError when it has surrounding
+    # whitespace or control characters (a key read from a file with its
+    # newline). Such a key would fail at the API, and the HTTP library's own
+    # error could quote it unredacted.
+    def check!(api_key)
+      key = api_key.to_s
+      if key != key.strip || key.match?(/[\u0000-\u001f\u007f]/)
+        raise ArgumentError, 'api_key has surrounding whitespace or control characters'
+      end
+
+      api_key
+    end
+  end
+end

data/lib/zerobounce/base_request.rb

@@ -3,6 +3,8 @@
 require 'json'
 require 'zerobounce/api_urls'
 require 'zerobounce/response_error'
+require 'zerobounce/api_key'
+require 'zerobounce/error'
 
 # https://github.com/rest-client/rest-client
 require 'rest-client'
@@ -70,6 +72,17 @@ module Zerobounce
       key.nil? ? Zerobounce.config.apikey : key
     end
 
+    # The key for this request, or an error before anything is sent. A key with
+    # surrounding whitespace or control characters (one read from a file with
+    # its newline) would go out as it is and fail, and the HTTP library could
+    # quote it unredacted.
+    def self.__checked_api_key__
+      api_key = current_api_key
+      raise ('API key must be assigned') if api_key.nil? || api_key.to_s.strip.empty?
+
+      ApiKey.check!(api_key)
+    end
+
     # The message for an HTTP error status.
     def self.__http_error_message__(error)
       code = error.http_code.to_i
@@ -109,8 +122,7 @@ module Zerobounce
       # puts path
       # puts Zerobounce.config.apikey
 
-      api_key = current_api_key
-      raise ('API key must be assigned') if api_key.nil? || api_key.to_s.strip.empty?
+      api_key = __checked_api_key__
 
       params[:api_key] = api_key
       url = "#{Zerobounce::BaseRequest.__root_without_trailing_slashes__(root)}/#{path}"
@@ -122,8 +134,7 @@ module Zerobounce
 
     def self._post(root, path, params, content_type='application/json', filepath=nil)
 
-      api_key = current_api_key
-      raise ('API key must be assigned') if api_key.nil? || api_key.to_s.strip.empty?
+      api_key = __checked_api_key__
 
       params[:api_key] = api_key
       url = "#{Zerobounce::BaseRequest.__root_without_trailing_slashes__(root)}/#{path}"
@@ -165,8 +176,7 @@ module Zerobounce
     # parameter, which the Inbox Placement Tester requires and which keeps the
     # key out of request logs.
     def self.__execute_with_method__(method, url, params, form: nil, json: nil, bearer: false)
-      api_key = current_api_key
-      raise ('API key must be assigned') if api_key.nil? || api_key.to_s.strip.empty?
+      api_key = __checked_api_key__
 
       params = (params || {}).dup
       extra = {}
@@ -251,30 +261,72 @@ module Zerobounce
     def self.__raise_if_success_false__(response, parsed)
       return unless parsed.is_a?(Hash) && parsed.key?('success') && __success_means_failure__(parsed['success'])
 
-      raise ResponseError.message_from_parts(response.code, response.headers[:content_type].to_s, response.body.to_s)
+      raise ApiResponseError.new(
+        ResponseError.message_from_parts(response.code, response.headers[:content_type].to_s, response.body.to_s),
+        response.code
+      )
+    end
+
+    # A value that reads as an error: a non-blank String.
+    def self.__error_text__(value)
+      value.is_a?(String) && !value.strip.empty?
+    end
+
+    # An "error" value that means failure: anything but nil or a blank String.
+    def self.__error_value__(value)
+      !value.nil? && !(value.is_a?(String) && value.strip.empty?)
+    end
+
+    # The keys a message-only body is made of.
+    MESSAGE_KEYS = %w[error message error_message Message Error detail].freeze
+
+    # A body made only of message keys (no "success"), for the calls whose
+    # result is never a bare message.
+    def self.__raise_if_message_only__(response, parsed)
+      return if parsed.empty? || parsed.key?('success')
+      return unless parsed.keys.all? { |key| MESSAGE_KEYS.include?(key) }
+
+      text = MESSAGE_KEYS.map { |key| parsed[key] }.find { |value| __error_text__(value) }
+      raise ApiResponseError.new(ResponseError.strip_prefix(text), response.code) if text
+    end
+
+    # A dead or invalid key on an HTTP 200: no "success" field and a non-empty
+    # "Error" (LIVE: the filters spell it so) or "error_message".
+    def self.__raise_if_bare_error__(response, parsed)
+      return if parsed.key?('success')
+
+      %w[Error error_message].each do |key|
+        next unless __error_text__(parsed[key])
+
+        raise ApiResponseError.new(ResponseError.strip_prefix(parsed[key]), response.code)
+      end
     end
 
     def self.__parse_json_response__(response)
       body = response.body.to_s
       content_type = (response.headers[:content_type] || '').to_s
+      code = response.code
       if ResponseError.html?(body, content_type) || body.strip.empty?
-        raise ResponseError.message_from_parts(response.code, content_type, body)
+        raise ApiResponseError.new(ResponseError.message_from_parts(code, content_type, body), code)
       end
       begin
         parsed = JSON.parse(body)
       rescue JSON::ParserError
-        raise 'ZeroBounce returned a response that is not valid JSON.'
+        raise ApiResponseError.new('ZeroBounce returned a response that is not valid JSON.', code)
       end
       return parsed unless parsed.is_a?(Hash)
 
       __raise_if_success_false__(response, parsed)
 
-      raise ResponseError.strip_prefix(parsed['error']) if parsed.key?('error') && !parsed['error'].nil?
+      raise ApiResponseError.new(ResponseError.strip_prefix(parsed['error']), code) if __error_value__(parsed['error'])
       # The Inbox Placement Tester is a Django REST framework app and reports
       # its errors under "detail" rather than "error"/"message".
-      raise ResponseError.strip_prefix(parsed['detail']) if parsed.key?('detail') && !parsed['detail'].nil?
+      if __error_value__(parsed['detail'])
+        raise ApiResponseError.new(ResponseError.strip_prefix(parsed['detail']), code)
+      end
+      __raise_if_bare_error__(response, parsed)
       if parsed.key?('errors') && parsed['errors'].is_a?(Array) && !parsed['errors'].empty?
-        raise ResponseError.strip_prefix(parsed['errors'][0]['error'])
+        raise ApiResponseError.new(ResponseError.strip_prefix(parsed['errors'][0]['error']), code)
       end
       parsed
     end

data/lib/zerobounce/client.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
+require 'zerobounce/api_key'
+
 module Zerobounce
   # One API key. Package methods share Zerobounce.config; a Client does not.
   class Client
     def initialize(apikey)
+      ApiKey.check!(apikey) unless apikey.nil? || apikey.to_s.strip.empty?
       @apikey = apikey
     end
 
+    # Keeps the API key out of logs and consoles.
+    def inspect
+      "#<#{self.class.name} apikey=#{@apikey.nil? ? 'nil' : '[FILTERED]'}>"
+    end
+
     def validate(email, ip_address = nil, **options)
       Zerobounce.with_api_key(@apikey) { Zerobounce.validate(email, ip_address, **options) }
     end

data/lib/zerobounce/error.rb

@@ -59,10 +59,12 @@ module Zerobounce
   # Carries the HTTP status so callers can tell a 403 (Cloudflare) from a
   # 400/404 (API) or a 429 (the Warmup rate limit). The Warmup client raises
   # it. The validation client raises the RestClient exception for an HTTP
-  # error status (status in #http_code), as it did up to 2.1.8, and a
-  # RuntimeError for an error reported with an HTTP 200; both carry the same
-  # short message.
-  class ApiResponseError < StandardError
+  # error status (status in #http_code), as it did up to 2.1.8, and this
+  # class, with the 2xx status (usually 200), for an error reported on a
+  # successful HTTP response; both carry the same short message. It is a
+  # RuntimeError, which those errors were before, so `rescue RuntimeError`
+  # still catches them.
+  class ApiResponseError < RuntimeError
     # @return [Integer] the HTTP status of the failed response, or 0
     attr_reader :status_code
 

data/lib/zerobounce/get_file_helper.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'stringio'
+require 'zerobounce/error'
 require 'zerobounce/response_error'
 
 module Zerobounce
@@ -70,12 +71,13 @@ module Zerobounce
       body_str = response.body.to_s
       ct = (response.headers[:content_type] || response.headers['Content-Type'] || '').to_s
 
-      if code > 299 || ResponseError.html?(body_str, ct)
-        raise ResponseError.message_from_parts(code, ct, body_str)
+      # An empty body is no result file: an error, as in the other SDKs.
+      if code > 299 || body_str.strip.empty? || ResponseError.html?(body_str, ct)
+        raise ApiResponseError.new(ResponseError.message_from_parts(code, ct, body_str), code)
       end
 
       if should_treat_as_error?(body_str, ct)
-        raise format_error_message(body_str)
+        raise ApiResponseError.new(format_error_message(body_str), code)
       end
 
       io = StringIO.new(response.body)

data/lib/zerobounce/priority3.rb

@@ -27,7 +27,7 @@ module Zerobounce
       end
 
       params = { domain_column: domain_column }
-      params[:has_header_row] = has_header_row ? 'true' : 'false' unless has_header_row.nil?
+      params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
       params[:first_name_column] = first_name_column unless first_name_column.nil?
       params[:last_name_column] = last_name_column unless last_name_column.nil?
       params[:middle_name_column] = middle_name_column unless middle_name_column.nil?
@@ -51,7 +51,7 @@ module Zerobounce
       raise ArgumentError, 'domain_column is required' if domain_column.nil? || domain_column.to_i < 1
 
       params = { domain_column: domain_column }
-      params[:has_header_row] = has_header_row ? 'true' : 'false' unless has_header_row.nil?
+      params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
       zb_request.bulk_root_post("#{DOMAIN_SEARCH_BULK_BASE}/sendfile", params, 'multipart/form-data', filepath)
     end
 
@@ -287,6 +287,26 @@ module Zerobounce
       value.nil? || value.to_s.strip.empty?
     end
 
+    # A boolean option, parsed strictly: true/false, 'true'/'false' in any
+    # case, or 1/0. Anything else is an ArgumentError, so 'false' can no
+    # longer be sent as true and a typo is not silently taken as a flag.
+    def __strict_bool__(value, name)
+      return value if [true, false].include?(value)
+      return value == 1 if value.is_a?(Integer) && [0, 1].include?(value)
+
+      if value.is_a?(String)
+        text = value.strip.downcase
+        return true if %w[true 1].include?(text)
+        return false if %w[false 0].include?(text)
+      end
+      raise ArgumentError, "#{name} must be true or false"
+    end
+
+    # A strict boolean option as the string the API expects on the wire.
+    def __wire_bool__(value, name)
+      __strict_bool__(value, name) ? 'true' : 'false'
+    end
+
     def __inbox_placement_test_type__(value)
       test_type = value.is_a?(Integer) ? value : value.to_s.strip.to_i
       unless INBOX_PLACEMENT_TEST_TYPES.include?(test_type)
@@ -311,12 +331,12 @@ module Zerobounce
       return_url = options[:return_url]
 
       params = {
-        has_header_row: has_header_row ? 'true' : 'false',
+        has_header_row: __wire_bool__(has_header_row, 'has_header_row'),
         file_name: file_name,
         return_url: return_url
       }
       if options.key?(:remove_duplicates)
-        params[:remove_duplicates] = options[:remove_duplicates] ? 'true' : 'false'
+        params[:remove_duplicates] = __wire_bool__(options[:remove_duplicates], 'remove_duplicates')
       end
 
       zb_request.bulk_root_form_post(path, params)

data/lib/zerobounce/request.rb

@@ -9,9 +9,14 @@ module Zerobounce
   # Sends the HTTP request.
   class Request < BaseRequest
 
-    # LIVE: these answer a success with a bare {"Message": "..."} body, which
-    # everywhere else means the request was rejected.
-    FILTER_PATHS = %w[filters/add filters/delete filters/list].freeze
+    # The email finder and domain search. Their result is never a bare
+    # message, so a body made only of message keys is how they report a
+    # rejected request. LIVE: an invalid or drained key gets an HTTP 200 with
+    # {"Message": "Invalid API key or your account ran out of credits"}.
+    # Everywhere else a bare message is a result: validate's greylist answer
+    # {"Message": "Greylist validation still in progress..."} and the
+    # filters' {"Message": "Filter successfully added"}.
+    MESSAGE_ONLY_ERROR_PATHS = %w[guessformat].freeze
 
     def self.get(path, params, content_type='application/json')
       response = self._get(Zerobounce.configuration.api_root_url, path, params, content_type)
@@ -25,11 +30,14 @@ module Zerobounce
         response_body_json = JSON.parse(response_body)
         return response_body_json unless response_body_json.is_a?(Hash)
 
-        raise (response_body_json['error']) if response_body_json.key?('error')
-        raise (response_body_json['errors'][0]['error']) \
-          if response_body_json.key?('errors') and \
-            response_body_json['errors'].length > 0
+        if __error_value__(response_body_json['error'])
+          raise ApiResponseError.new(ResponseError.strip_prefix(response_body_json['error']), response.code)
+        end
+        if response_body_json['errors'].is_a?(Array) && !response_body_json['errors'].empty?
+          raise ApiResponseError.new(response_body_json['errors'][0]['error'].to_s, response.code)
+        end
         __raise_if_success_false__(response, response_body_json)
+        __raise_if_bare_error__(response, response_body_json)
 
         return response_body_json
       else
@@ -94,35 +102,30 @@ module Zerobounce
       content_type = (response.headers[:content_type] || '').to_s
       if ResponseError.html?(body, content_type) || body.strip.empty? ||
          (!content_type.include?('json') && !body.strip.start_with?('{', '['))
-        raise ResponseError.message_from_parts(response.code, content_type, body)
+        raise ApiResponseError.new(ResponseError.message_from_parts(response.code, content_type, body), response.code)
       end
       begin
         parsed = JSON.parse(body)
       rescue JSON::ParserError
-        raise 'ZeroBounce returned a response that is not valid JSON.'
+        raise ApiResponseError.new('ZeroBounce returned a response that is not valid JSON.', response.code)
       end
       return parsed unless parsed.is_a?(Hash)
 
-      raise ResponseError.strip_prefix(parsed['error']) if parsed.key?('error') && !parsed['error'].nil?
-      __raise_if_success_false__(response, parsed)
-      # LIVE: the filters spell it "Error". An invalid or drained key answers
-      # them with {"Error": "Invalid API key or your account ran out of
-      # credits"} on an HTTP 200, which used to come back as their result.
-      if !parsed.key?('success') && parsed['Error'].is_a?(String) && !parsed['Error'].strip.empty?
-        raise ResponseError.strip_prefix(parsed['Error'])
-      end
-      # A body that is nothing but "Message" is how the validate endpoints
-      # report a rejected request. The filters endpoints use the same shape for
-      # a *success* ("Filter successfully added"), so they are left out.
-      if parsed.key?('Message') && parsed.length == 1 && !FILTER_PATHS.include?(path)
-        raise ResponseError.strip_prefix(parsed['Message'])
+      code = response.code
+      if __error_value__(parsed['error'])
+        raise ApiResponseError.new(ResponseError.strip_prefix(parsed['error']), code)
       end
+      __raise_if_success_false__(response, parsed)
+      __raise_if_bare_error__(response, parsed)
+      __raise_if_message_only__(response, parsed) if MESSAGE_ONLY_ERROR_PATHS.include?(path)
       if parsed.key?('errors') && parsed['errors'].is_a?(Array) && !parsed['errors'].empty?
         account = parsed['errors'].find { |item| item.is_a?(Hash) && item['email_address'].to_s.casecmp('all').zero? }
         if account
-          raise ResponseError.strip_prefix(account['error'])
+          raise ApiResponseError.new(ResponseError.strip_prefix(account['error']), code)
+        end
+        unless path == 'validatebatch'
+          raise ApiResponseError.new(ResponseError.strip_prefix(parsed['errors'][0]['error']), code)
         end
-        raise ResponseError.strip_prefix(parsed['errors'][0]['error']) unless path == 'validatebatch'
       end
       parsed
     end

data/lib/zerobounce/version.rb

@@ -2,5 +2,5 @@
 
 module Zerobounce
   # The version of the gem.
-  VERSION = '2.2.0'
+  VERSION = '3.0.0'
 end

data/lib/zerobounce/warmup.rb

@@ -5,6 +5,7 @@ require 'erb'
 require 'json'
 require 'rest-client'
 
+require 'zerobounce/api_key'
 require 'zerobounce/error'
 require 'zerobounce/response_error'
 
@@ -40,9 +41,7 @@ module Zerobounce
 
       # A key with surrounding whitespace or control characters would be
       # quoted, unredacted, in the HTTP library's own error.
-      if api_key != api_key.strip || api_key.match?(/[\u0000-\u001f\u007f]/)
-        raise ArgumentError, 'api_key has surrounding whitespace or control characters'
-      end
+      ApiKey.check!(api_key)
       unless base_url.to_s.downcase.start_with?('https://')
         raise ArgumentError, 'base_url must be an https:// URL'
       end
@@ -53,6 +52,11 @@ module Zerobounce
       @root = "#{root}#{BASE_PATH}"
     end
 
+    # Keeps the API key out of logs and consoles.
+    def inspect
+      "#<#{self.class.name} root=#{@root.inspect} api_key=[FILTERED]>"
+    end
+
     # -- sending accounts ---------------------------------------------------
 
     # Every sending account of the key's team. GET /sending-accounts

data/lib/zerobounce.rb

@@ -14,7 +14,6 @@ require 'zerobounce/get_file_helper'
 require 'zerobounce/validate_status'
 require 'zerobounce/validate_sub_status'
 require 'zerobounce/request'
-require 'zerobounce/mock_request'
 require 'zerobounce/configuration'
 require 'zerobounce/api_urls'
 require 'zerobounce/priority3'
@@ -27,7 +26,7 @@ module Zerobounce
     include Priority3
     attr_writer :configuration
 
-    @@request = ENV['TEST']=='unit' ? MockRequest : Request
+    @@request = Request
 
     # Zerobounce configuration
     #
@@ -102,6 +101,10 @@ module Zerobounce
           raise ArgumentError, 'Invalid parameter: timeout (must be between 3 and 60 seconds)'
         end
       end
+      activity_data = __strict_bool__(activity_data, 'activity_data') unless activity_data.nil?
+      verify_plus = __strict_bool__(verify_plus, 'verify_plus') unless verify_plus.nil?
+      domain_info = __strict_bool__(domain_info, 'domain_info') unless domain_info.nil?
+      greylist_processing = __strict_bool__(greylist_processing, 'greylist_processing') unless greylist_processing.nil?
       unless callback_url.nil?
         raise ArgumentError, 'Empty parameter: callback_url' if callback_url.to_s.strip.empty?
 
@@ -312,8 +315,8 @@ module Zerobounce
       # the API rejects the whole batch with the account-level "Invalid API Key
       # or your account ran out of credits".
       params[:timeout] = timeout.to_s unless timeout.nil?
-      params[:activity_data] = activity_data unless activity_data.nil?
-      params[:verify_plus] = verify_plus unless verify_plus.nil?
+      params[:activity_data] = __strict_bool__(activity_data, 'activity_data') unless activity_data.nil?
+      params[:verify_plus] = __strict_bool__(verify_plus, 'verify_plus') unless verify_plus.nil?
       results = @@request.post('validatebatch', params)
       results
     end
@@ -345,16 +348,14 @@ module Zerobounce
         return_url: nil,
         allow_phase_2: nil
       )
-      params = {
-        email_address_column: email_address_column,
-        has_header_row: has_header_row,
-      }
+      params = { email_address_column: email_address_column }
+      params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
       params[:first_name_column] = first_name_column unless first_name_column.nil?
       params[:last_name_column] = last_name_column unless last_name_column.nil?
       params[:gender_column] = gender_column unless gender_column.nil?
       params[:return_url] = return_url unless return_url.nil? || return_url.to_s.empty?
       unless allow_phase_2.nil?
-        params[:allow_phase_2] = allow_phase_2 ? 'true' : 'false'
+        params[:allow_phase_2] = __wire_bool__(allow_phase_2, 'allow_phase_2')
       end
       @@request.bulk_post('sendfile', params, 'multipart/form-data', filepath)
     end
@@ -414,7 +415,7 @@ module Zerobounce
       if options
         params[:download_type] = options.download_type if options.download_type
         unless options.activity_data.nil?
-          params[:activity_data] = options.activity_data ? 'true' : 'false'
+          params[:activity_data] = __wire_bool__(options.activity_data, 'activity_data')
         end
       end
       @@request.bulk_getfile('getfile', params)
@@ -457,10 +458,8 @@ module Zerobounce
         has_header_row: true,
         return_url: nil
       )
-      params = {
-        email_address_column: email_address_column,
-        has_header_row: has_header_row,
-      }
+      params = { email_address_column: email_address_column }
+      params[:has_header_row] = __wire_bool__(has_header_row, 'has_header_row') unless has_header_row.nil?
       params[:return_url] = return_url if return_url
       @@request.bulk_post('scoring/sendfile', params, 'multipart/form-data', filepath)
     end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: zerobounce-sdk
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Zero Bounce
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-11-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -94,6 +93,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: racc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -282,7 +309,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.4'
-description: A Ruby client for Zerobounce.net.
+description: 'The official Ruby client for the ZeroBounce API: real-time and batch
+  email validation, AI scoring, bulk file validation and scoring, email finder and
+  domain search, the list evaluator, filters, the Inbox Placement Tester and Warmup.'
 email:
 - integrations@zerobounce.net
 executables: []
@@ -291,9 +320,9 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
-- LICENSE.txt
 - README.md
 - lib/zerobounce.rb
+- lib/zerobounce/api_key.rb
 - lib/zerobounce/api_urls.rb
 - lib/zerobounce/base_request.rb
 - lib/zerobounce/client.rb
@@ -302,7 +331,6 @@ files:
 - lib/zerobounce/error.rb
 - lib/zerobounce/get_file_helper.rb
 - lib/zerobounce/get_file_options.rb
-- lib/zerobounce/mock_request.rb
 - lib/zerobounce/priority3.rb
 - lib/zerobounce/request.rb
 - lib/zerobounce/response_error.rb
@@ -315,7 +343,9 @@ licenses:
 - MIT
 metadata:
   yard.run: yri
-post_install_message:
+  homepage_uri: https://zerobounce.net
+  source_code_uri: https://github.com/zerobounce/zero-bounce-ruby
+  changelog_uri: https://github.com/zerobounce/zero-bounce-ruby/blob/develop/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -330,8 +360,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: A Ruby client for Zerobounce.net.
+summary: 'Official ZeroBounce Ruby SDK: email validation, AI scoring, bulk files,
+  email finder and domain search'
 test_files: []

data/LICENSE.txt

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 ZeroBounce
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

data/lib/zerobounce/mock_request.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-require 'zerobounce/base_request'
-require 'zerobounce/get_file_helper'
-
-module Zerobounce
-
-  # Sends the HTTP request.
-  class MockRequest < BaseRequest
-
-    def self.get(path, params, content_type='application/json')
-      response = self._get(Zerobounce.configuration.api_root_url, path, params, content_type)
-      if __json_content_type__(response.headers[:content_type])
-        response_body = response.body
-        response_body_json = JSON.parse(response_body)
-
-        raise (response_body_json['error']) if response_body_json.key?('error')
-        raise (response_body_json['errors'][0]['error']) \
-          if response_body_json.key?('errors') and \
-            response_body_json['errors'].length > 0
-
-        return response_body_json
-      else
-        return response
-      end
-    end
-
-    def self.bulk_get(path, params, content_type='application/json')
-      response = self._get(Zerobounce.configuration.bulk_api_root_url, path, params, content_type)
-      if __json_content_type__(response.headers[:content_type])
-        response_body = response.body
-        response_body_json = JSON.parse(response_body)
-        return response_body_json unless response_body_json.is_a?(Hash)
-
-        raise (response_body_json['error']) if response_body_json.key?('error')
-        raise (response_body_json['errors'][0]['error']) \
-          if response_body_json.key?('errors') and \
-            response_body_json['errors'].length > 0
-
-        return response_body_json
-      else
-        return response.body
-      end
-    end
-
-    def self.bulk_getfile(path, params)
-      response = self._get(Zerobounce.configuration.bulk_api_root_url, path, params, 'application/json')
-      GetFileHelper.process_getfile_response(response)
-    end
-
-    def self.post(path, params, content_type='application/json', filepath=nil)
-      response = self._post(Zerobounce.configuration.api_root_url, path, params, \
-          content_type, filepath)
-      if __json_content_type__(response.headers[:content_type])
-        response_body = response.body
-        response_body_json = JSON.parse(response_body)
-
-        raise (response_body_json['error']) if response_body_json.key?('error')
-        raise (response_body_json['errors'][0]['error']) \
-          if response_body_json.key?('errors') and \
-            response_body_json['errors'].length > 0
-
-        return response_body_json
-      end
-      return response.body
-    end
-
-    def self.bulk_post(path, params, content_type='application/json', filepath=nil)
-      response = self._post(Zerobounce.configuration.bulk_api_root_url, path, params, \
-          content_type, filepath)
-      if __json_content_type__(response.headers[:content_type])
-        return __parse_json_response__(response)
-      end
-      response.body
-    end
-
-    def self.bulk_root_get(path, params, content_type='application/json')
-      response = self._get(bulk_api_root_without_v2, path, params, content_type)
-      if __json_content_type__(response.headers[:content_type])
-        return __parse_json_response__(response)
-      end
-      response.body
-    end
-
-    def self.bulk_root_getfile(path, params)
-      response = self._get(bulk_api_root_without_v2, path, params, 'application/json')
-      GetFileHelper.process_getfile_response(response)
-    end
-
-    def self.bulk_root_post(path, params, content_type='application/json', filepath=nil)
-      response = self._post(bulk_api_root_without_v2, path, params, content_type, filepath)
-      if __json_content_type__(response.headers[:content_type])
-        return __parse_json_response__(response)
-      end
-      response.body
-    end
-
-    def self.bulk_root_form_post(path, params)
-      response = self._post(bulk_api_root_without_v2, path, params, 'application/x-www-form-urlencoded')
-      __parse_json_response__(response)
-    end
-
-  end
-
-end