zerobounce-sdk 2.1.8 → 3.0.0

data/lib/zerobounce.rb

@@ -5,6 +5,8 @@ require 'date'
 require 'tempfile'
 
 require 'zerobounce/error'
+require 'zerobounce/response_error'
+require 'zerobounce/client'
 require 'zerobounce/version'
 require 'zerobounce/download_type'
 require 'zerobounce/get_file_options'
@@ -12,17 +14,19 @@ 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'
+require 'zerobounce/warmup'
 
 # Validate an email address with Zerobounce.net
 module Zerobounce
 
   class << self
+    include Priority3
     attr_writer :configuration
 
-    @@request = ENV['TEST']=='unit' ? MockRequest : Request
+    @@request = Request
 
     # Zerobounce configuration
     #
@@ -52,6 +56,15 @@ module Zerobounce
       yield configuration
     end
 
+    # Run a block with an API key that is visible only on this thread.
+    def with_api_key(api_key)
+      previous = Thread.current[:zerobounce_api_key]
+      Thread.current[:zerobounce_api_key] = api_key
+      yield
+    ensure
+      Thread.current[:zerobounce_api_key] = previous
+    end
+
     # Validates the email address and gets geoip information for an IP if provided.
     #
     # @param [String] :email The email address to validate.
@@ -80,9 +93,47 @@ module Zerobounce
     #   "zipcode": null,
     #   "processed_at": "2023-04-18 12:09:39.074"
     # }
-    def validate(email, ip_address=nil)
+    def validate(email, ip_address=nil, timeout: nil, activity_data: nil, verify_plus: nil,
+                 domain_info: nil, greylist_processing: nil, callback_url: nil, use_post: false)
+      unless timeout.nil?
+        timeout_i = Integer(timeout)
+        if timeout_i < 3 || timeout_i > 60
+          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?
+
+        # The callback is where the greylist retry posts its result, so it is
+        # meaningless - and rejected by the API - without the retry itself.
+        unless greylist_processing
+          raise ArgumentError, 'callback_url requires greylist_processing to be true'
+        end
+      end
       params = {email: email, ip_address: ip_address}
-      @@request.get('validate', params)
+      params[:timeout] = timeout unless timeout.nil?
+      unless activity_data.nil?
+        params[:activity_data] = activity_data ? 'true' : 'false'
+      end
+      unless verify_plus.nil?
+        params[:verify_plus] = verify_plus ? 'true' : 'false'
+      end
+      unless domain_info.nil?
+        params[:domain_info] = domain_info ? 'true' : 'false'
+      end
+      unless greylist_processing.nil?
+        params[:greylist_processing] = greylist_processing ? 'true' : 'false'
+      end
+      params[:callback_url] = callback_url unless callback_url.nil?
+      if use_post
+        @@request.post('validate', params, 'application/x-www-form-urlencoded')
+      else
+        @@request.get('validate', params)
+      end
     end
 
     # Get the number of remaining credits on the account.
@@ -183,13 +234,33 @@ module Zerobounce
       @@request.get('activity', params)
     end
 
+    # Real-time AI scoring for a single email (GET /scoring by default).
+    #
+    # @param [String] :email Email to score
+    # @param [Boolean] :use_post When true, uses POST /scoring with form body
+    #
+    # @return [Hash] e.g. {"email"=>"mark@gmail.com", "score"=>10}
+    def score_email(email, use_post: false)
+      params = { email: email }
+      if use_post
+        @@request.post('scoring', params, 'application/x-www-form-urlencoded')
+      else
+        @@request.get('scoring', params)
+      end
+    end
+
     # Validate email batch
     #
     # @param [Array] :emails List of email addresses to validate.
     # @option [Array] :ip_addresses Corresponding list of IP addresses.
     #
-    # @return [Array] list of validate result for each element
-    # [
+    # @return [Hash] the whole response: +email_batch+ holds one validate
+    #   result per address, +errors+ the addresses that could not be
+    #   validated. A per-address error does not raise; an account-level one
+    #   (reported for the address "all", e.g. an invalid key) does.
+    #   Up to 2.1.8 this returned only the +email_batch+ Array.
+    # {
+    #   "email_batch": [
     #   {
     #     "address": "disposable@example.com",
     #     "status": "do_not_mail",
@@ -216,8 +287,16 @@ module Zerobounce
     #     ...
     #   },
     #   ...
-    # ]
-    def validate_batch(emails, ip_addresses=[])
+    #   ],
+    #   "errors": []
+    # }
+    def validate_batch(emails, ip_addresses=[], timeout: nil, activity_data: nil, verify_plus: nil)
+      unless timeout.nil?
+        timeout_i = Integer(timeout)
+        if timeout_i < 10 || timeout_i > 120
+          raise ArgumentError, 'Invalid parameter: timeout (must be between 10 and 120 seconds)'
+        end
+      end
 
       raise ArgumentError.new if emails.class != Array
       emails.each do |email|
@@ -232,8 +311,14 @@ module Zerobounce
         })
       end
       params = {email_batch: email_batch}
+      # LIVE: 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".
+      params[:timeout] = timeout.to_s unless timeout.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)
-      return results['email_batch']
+      results
     end
 
     # Validate CSV file
@@ -263,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[:first_name_column] = first_name_column if first_name_column
-      params[:last_name_column] = last_name_column if last_name_column
-      params[:gender_column] = gender_column if gender_column
-      params[:return_url] = return_url if return_url
+      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
@@ -332,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)
@@ -375,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
@@ -513,7 +594,8 @@ module Zerobounce
     #
     # @option [String] domain Domain to search within (e.g. example.com). Required if company_name is not provided.
     # @option [String] company_name Company name to search within (e.g. Example). Required if domain is not provided.
-    # @option [String] first_name First name of target.
+    # @param [String] first_name First name of target. Optional: left out, the
+    #   call answers with the domain's format rather than one person's address.
     # @option [String] middle_name Middle name of target.
     # @option [String] last_name Last name of target.
     #
@@ -526,7 +608,10 @@ module Zerobounce
     #   "did_you_mean": "",
     #   "failure_reason": ""
     # }
-    def find_email(first_name, domain: '', company_name: '', middle_name: '', last_name: '')
+    # first_name is optional: /guessformat only requires a domain or a company
+    # name, and answers the domain's format when no name is given. It stays the
+    # first positional argument, so every existing call keeps working.
+    def find_email(first_name = nil, domain: '', company_name: '', middle_name: '', last_name: '')
       # Validate that exactly one of domain or company_name is provided
       if (domain.nil? || domain.empty?) && (company_name.nil? || company_name.empty?)
         raise ArgumentError, "Either domain or company_name must be provided"
@@ -534,7 +619,8 @@ module Zerobounce
         raise ArgumentError, "Only one of domain or company_name can be provided"
       end
 
-      params = { first_name: first_name }
+      params = {}
+      params[:first_name] = first_name unless first_name.nil? || first_name.to_s.empty?
       params[:domain] = domain unless domain.nil? || domain.empty?
       params[:company_name] = company_name unless company_name.nil? || company_name.empty?
       params[:middle_name] = middle_name unless middle_name.nil? || middle_name.empty?

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: zerobounce-sdk
 version: !ruby/object:Gem::Version
-  version: 2.1.8
+  version: 3.0.0
 platform: ruby
 authors:
 - Zero Bounce
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -31,7 +30,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -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,65 +309,43 @@ 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: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".dockerignore"
-- ".env.example"
-- ".github/auto_assign.yml"
-- ".github/dependabot.yml"
-- ".github/workflows/auto_assign_ci.yaml"
-- ".github/workflows/codeql.yml"
-- ".github/workflows/publish.yml"
-- ".github/workflows/sdk_ci.yml"
-- ".gitignore"
-- ".rspec"
-- ".ruby-version"
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
-- CONTRIBUTING.md
-- Dockerfile
-- Gemfile
-- Gemfile.lock
 - LICENSE
-- LICENSE.txt
 - README.md
-- Rakefile
-- SECURITY.md
-- bin/bundle
-- bin/console
-- bin/setup
-- data/zerobounce-ai-scoring.csv
-- data/zerobounce-batch-validation.csv
-- documentation.md
-- files/scoring.csv
-- files/validation.csv
-- files/zerobounce-ai-scoring.csv
-- files/zerobounce-batch-validation.csv
 - lib/zerobounce.rb
+- lib/zerobounce/api_key.rb
 - lib/zerobounce/api_urls.rb
 - lib/zerobounce/base_request.rb
+- lib/zerobounce/client.rb
 - lib/zerobounce/configuration.rb
 - lib/zerobounce/download_type.rb
 - 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
 - lib/zerobounce/validate_status.rb
 - lib/zerobounce/validate_sub_status.rb
 - lib/zerobounce/version.rb
-- zerobounce.gemspec
+- lib/zerobounce/warmup.rb
 homepage: https://zerobounce.net
 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
@@ -348,15 +353,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !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/.dockerignore

@@ -1,17 +0,0 @@
-# Keep .git so gemspec `git ls-files` works during `bundle install` in the image.
-
-# Docs and tooling not needed to run specs in the image
-*.md
-documentation*.md
-.spec
-.rspec_status
-coverage/
-tmp/
-pkg/
-vendor/bundle
-
-# OS & env
-.DS_Store
-Thumbs.db
-.env
-.env.*

data/.env.example

@@ -1,3 +0,0 @@
-# ZeroBounce API key (standard). Get your key at https://www.zerobounce.net/docs/api-dashboard
-# Copy this file to .env and set your key.
-ZEROBOUNCE_API_KEY=your_api_key_here

data/.github/auto_assign.yml

@@ -1,5 +0,0 @@
-addReviewers: false
-addAssignees: true
-assignees:
-  - franciscbalint
-numberOfAssignees: 1

data/.github/dependabot.yml

@@ -1,35 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#versioning-strategy
-
-version: 2
-updates:
-  # Keep the Ruby dependencies up to date
-  - package-ecosystem: "bundler"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-      day: "monday"
-    target-branch: "develop"
-    labels:
-      - "ruby dependencies"
-    groups:
-      bundler:
-        applies-to: version-updates
-        patterns:
-          - "*"
-
-  # Keep the Github Actions dependencies up to date
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-      day: "monday"
-    target-branch: "develop"
-    labels:
-      - "github dependencies"
-    groups:
-      github:
-        applies-to: version-updates
-        patterns:
-          - "*"

data/.github/workflows/auto_assign_ci.yaml

@@ -1,21 +0,0 @@
-name: Auto Assign
-
-on:
-  pull_request_target:
-    types:
-      - opened
-      - synchronize
-      - reopened
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  add-assignee:
-    name: Auto assign (me only)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: kentaro-m/auto-assign-action@v2.0.2
-        with:
-          configuration-path: ".github/auto_assign.yml"

data/.github/workflows/codeql.yml

@@ -1,105 +0,0 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
-name: "CodeQL Advanced"
-
-on:
-  push:
-    branches: [ "develop" ]
-  pull_request:
-    branches: [ "develop" ]
-  schedule:
-    - cron: '19 14 * * 4'
-
-permissions:
-  security-events: write
-  packages: read
-  actions: read
-  contents: read
-
-jobs:
-  analyze:
-    name: Analyze (${{ matrix.language }})
-    # Runner size impacts CodeQL analysis time. To learn more, please see:
-    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
-    #   - https://gh.io/supported-runners-and-hardware-resources
-    #   - https://gh.io/using-larger-runners (GitHub.com only)
-    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
-    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
-    permissions:
-      # required for all workflows
-      security-events: write
-
-      # required to fetch internal or private CodeQL packs
-      packages: read
-
-      # only required for workflows in private repositories
-      actions: read
-      contents: read
-
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-        - language: ruby
-          build-mode: none
-        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
-        # Use `c-cpp` to analyze code written in C, C++ or both
-        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
-        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
-        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
-        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
-        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
-        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v7
-
-    # Add any setup steps before running the `github/codeql-action/init` action.
-    # This includes steps like installing compilers or runtimes (`actions/setup-node`
-    # or others). This is typically only required for manual builds.
-    # - name: Setup runtime (example)
-    #   uses: actions/setup-example@v1
-
-    # Initializes the CodeQL tools for scanning.
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v4.36.3
-      with:
-        languages: ${{ matrix.language }}
-        build-mode: ${{ matrix.build-mode }}
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file.
-        # Prefix the list here with "+" to use these queries and those in the config file.
-
-        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
-        # queries: security-extended,security-and-quality
-
-    # If the analyze step fails for one of the languages you are analyzing with
-    # "We were unable to automatically build your code", modify the matrix above
-    # to set the build mode to "manual" for that language. Then modify this step
-    # to build your code.
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
-    - name: Run manual build steps
-      if: matrix.build-mode == 'manual'
-      shell: bash
-      run: |
-        echo 'If you are using a "manual" build mode for one or more of the' \
-          'languages you are analyzing, replace this with the commands to build' \
-          'your code, for example:'
-        echo '  make bootstrap'
-        echo '  make release'
-        exit 1
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v4.36.3
-      with:
-        category: "/language:${{matrix.language}}"