zerobounce-sdk 1.1.2 → 2.0.13

data/lib/zerobounce/request.rb

@@ -9,7 +9,7 @@ module Zerobounce
   class Request < BaseRequest
 
     def self.get(path, params, content_type='application/json')
-      response = self._get(Zerobounce::API_ROOT_URL, path, params, content_type)
+      response = self._get(Zerobounce.configuration.api_root_url, path, params, content_type)
       if response.headers[:content_type] == 'application/json'
         response_body = response.body
         response_body_json = JSON.parse(response_body)
@@ -29,7 +29,7 @@ module Zerobounce
     end
 
     def self.bulk_get(path, params, content_type='application/json')
-      response = self._get(Zerobounce::BULK_API_ROOT_URL, path, params, content_type)
+      response = self._get(Zerobounce.configuration.bulk_api_root_url, path, params, content_type)
       if response.headers[:content_type] == 'application/json'
         response_body = response.body
         response_body_json = JSON.parse(response_body)
@@ -48,7 +48,7 @@ module Zerobounce
     end
 
     def self.bulk_post(path, params, content_type='application/json', filepath=nil)
-      response = self._post(Zerobounce::BULK_API_ROOT_URL, path, params, \
+      response = self._post(Zerobounce.configuration.bulk_api_root_url, path, params, \
           content_type, filepath)
       if response.headers[:content_type] == 'application/json'
         response_body = response.body

data/lib/zerobounce/validate_status.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  # Validation status values returned by the API (validate, validate_batch).
+  # Use for comparison: response['status'] == Zerobounce::ValidateStatus::VALID
+  # Unknown/future API values are not listed; compare against response['status'] as string.
+  module ValidateStatus
+    NONE = ''
+    VALID = 'valid'
+    INVALID = 'invalid'
+    CATCH_ALL = 'catch-all'
+    UNKNOWN = 'unknown'
+    SPAMTRAP = 'spamtrap'
+    ABUSE = 'abuse'
+    DO_NOT_MAIL = 'do_not_mail'
+  end
+end

data/lib/zerobounce/validate_sub_status.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  # Validation sub-status values returned by the API (validate, validate_batch).
+  # Use for comparison: response['sub_status'] == Zerobounce::ValidateSubStatus::ACCEPT_ALL
+  # Unknown/future API values are not listed; compare against response['sub_status'] as string.
+  module ValidateSubStatus
+    NONE = ''
+    ANTISPAM_SYSTEM = 'antispam_system'
+    GREYLISTED = 'greylisted'
+    MAIL_SERVER_TEMPORARY_ERROR = 'mail_server_temporary_error'
+    FORCIBLE_DISCONNECT = 'forcible_disconnect'
+    MAIL_SERVER_DID_NOT_RESPOND = 'mail_server_did_not_respond'
+    TIMEOUT_EXCEEDED = 'timeout_exceeded'
+    FAILED_SMTP_CONNECTION = 'failed_smtp_connection'
+    MAILBOX_QUOTA_EXCEEDED = 'mailbox_quota_exceeded'
+    EXCEPTION_OCCURRED = 'exception_occurred'
+    POSSIBLE_TRAP = 'possible_trap'
+    ROLE_BASED = 'role_based'
+    GLOBAL_SUPPRESSION = 'global_suppression'
+    MAILBOX_NOT_FOUND = 'mailbox_not_found'
+    NO_DNS_ENTRIES = 'no_dns_entries'
+    FAILED_SYNTAX_CHECK = 'failed_syntax_check'
+    POSSIBLE_TYPO = 'possible_typo'
+    UNROUTABLE_IP_ADDRESS = 'unroutable_ip_address'
+    LEADING_PERIOD_REMOVED = 'leading_period_removed'
+    DOES_NOT_ACCEPT_MAIL = 'does_not_accept_mail'
+    ALIAS_ADDRESS = 'alias_address'
+    ROLE_BASED_CATCH_ALL = 'role_based_catch_all'
+    DISPOSABLE = 'disposable'
+    TOXIC = 'toxic'
+    ALTERNATE = 'alternate'
+    MX_FORWARD = 'mx_forward'
+    BLOCKED = 'blocked'
+    ALLOWED = 'allowed'
+    ACCEPT_ALL = 'accept_all'
+    ROLE_BASED_ACCEPT_ALL = 'role_based_accept_all'
+    GOLD = 'gold'
+  end
+end

data/lib/zerobounce/version.rb

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

data/lib/zerobounce.rb

@@ -2,19 +2,20 @@
 # frozen_string_literal: true
 
 require 'date'
+require 'tempfile'
 
 require 'zerobounce/error'
 require 'zerobounce/version'
+require 'zerobounce/validate_status'
+require 'zerobounce/validate_sub_status'
 require 'zerobounce/request'
 require 'zerobounce/mock_request'
 require 'zerobounce/configuration'
+require 'zerobounce/api_urls'
 
 # Validate an email address with Zerobounce.net
 module Zerobounce
 
-  API_ROOT_URL      = 'https://api.zerobounce.net/v2'
-  BULK_API_ROOT_URL = 'https://bulkapi.zerobounce.net/v2'
-
   class << self
     attr_writer :configuration
 
@@ -135,10 +136,13 @@ module Zerobounce
     #   "sub_status_mailbox_quota_exceeded": 0,
     #   "sub_status_forcible_disconnect": 0,
     #   "sub_status_failed_smtp_connection": 0,
+    #   "sub_status_accept_all": 0,
     #   "sub_status_mx_forward": 0,
     #   "sub_status_alternate": 0,
-    #   "sub_status_blocked": 0,
     #   "sub_status_allowed": 0,
+    #   "sub_status_blocked": 0,
+    #   "sub_status_gold": 0,
+    #   "sub_status_role_based_accept_all": 0,
     #   "start_date": "1/1/2018",
     #   "end_date": "12/12/2023"
     # }
@@ -256,6 +260,27 @@ module Zerobounce
       @@request.bulk_post('sendfile', params, 'multipart/form-data', filepath)
     end
 
+    # Validate CSV from a stream (IO or String).
+    #
+    # @param [IO, String] io Stream or string content to upload
+    # @param [String] file_name Filename for the upload (e.g. "emails.csv")
+    # @option [Int] :email_address_column (same as validate_file_send)
+    # @option [Int] :first_name_column
+    # @option [Int] :last_name_column
+    # @option [Int] :gender_column
+    # @option [Int] :has_header_row
+    # @option [Int] :return_url
+    # @return [Hash] same as validate_file_send
+    def validate_file_send_stream(io, file_name, **opts)
+      content = io.respond_to?(:read) ? io.read : io.to_s
+      Tempfile.create(['zb', File.extname(file_name)]) do |tmp|
+        tmp.binmode
+        tmp.write(content)
+        tmp.rewind
+        validate_file_send(tmp.path, **opts)
+      end
+    end
+
     # Get validate file status
     #
     # @param [String] :file_id Id of the file.
@@ -333,6 +358,24 @@ module Zerobounce
       @@request.bulk_post('scoring/sendfile', params, 'multipart/form-data', filepath)
     end
 
+    # Score CSV from a stream (IO or String).
+    #
+    # @param [IO, String] io Stream or string content to upload
+    # @param [String] file_name Filename for the upload (e.g. "emails.csv")
+    # @option [Int] :email_address_column (same as scoring_file_send)
+    # @option [Int] :has_header_row
+    # @option [Int] :return_url
+    # @return [Hash] same as scoring_file_send
+    def scoring_file_send_stream(io, file_name, **opts)
+      content = io.respond_to?(:read) ? io.read : io.to_s
+      Tempfile.create(['zb', File.extname(file_name)]) do |tmp|
+        tmp.binmode
+        tmp.write(content)
+        tmp.rewind
+        scoring_file_send(tmp.path, **opts)
+      end
+    end
+
     # Get validate results file
     #
     # @param [String] :file_id Id of the file.
@@ -427,19 +470,120 @@ module Zerobounce
     #    ]
     # }
     def guessformat(domain, first_name: '', middle_name: '', last_name: '')
-      params = {
-        domain: domain
-      }
-      unless first_name.empty?
-        params['first_name'] = first_name
-      end
-      unless middle_name.empty?
-        params['middle_name'] = middle_name
+      warn "[DEPRECATION] `guessformat` is deprecated and will be removed in a future version.\n" \
+           "Please use `find_email` or `find_domain` instead."
+      params = {domain: domain}
+      params[:first_name] = first_name unless first_name.nil? || first_name.empty?
+      params[:middle_name] = middle_name unless middle_name.nil? || middle_name.empty?
+      params[:last_name] = last_name unless last_name.nil? || last_name.empty?  
+      @@request.get('guessformat', params)
+    end
+
+
+    # Find email address format
+    #
+    # @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.
+    # @option [String] middle_name Middle name of target.
+    # @option [String] last_name Last name of target.
+    #
+    # @return [Hash]
+    # {
+    #   "email": "john@zerobounce.net",
+    #   "email_confidence": "medium",
+    #   "domain": "zerobounce.net",
+    #   "company_name": "ZeroBounce",
+    #   "did_you_mean": "",
+    #   "failure_reason": ""
+    # }
+    def find_email(first_name, 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"
+      elsif !(domain.nil? || domain.empty?) && !(company_name.nil? || company_name.empty?)
+        raise ArgumentError, "Only one of domain or company_name can be provided"
       end
-      unless last_name.empty?
-        params['last_name'] = last_name
+
+      params = { first_name: first_name }
+      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?
+      params[:last_name] = last_name unless last_name.nil? || last_name.empty?
+
+      @@request.get('guessformat', params)
+    end
+
+    # Find domain format
+    # 
+    # @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.
+    # 
+    # @return [Hash]
+    # {
+    #   "domain": "zerobounce.net",
+    #   "company_name": "Hertza, LLC",
+    #   "format": "first.last",
+    #   "confidence": "high",
+    #   "did_you_mean": "",
+    #   "failure_reason": "",
+    #   "other_domain_formats": [
+    #     {"format": "first", "confidence": "high"},
+    #     {"format": "last.first", "confidence": "high"},
+    #     {"format": "lastfirst", "confidence": "high"},
+    #     {"format": "firstl", "confidence": "high"},
+    #     {"format": "lfirst", "confidence": "high"},
+    #     {"format": "firstlast", "confidence": "high"},
+    #     {"format": "last_middle_f", "confidence": "high"},
+    #     {"format": "last", "confidence": "high"},
+    #     {"format": "f.last", "confidence": "medium"},
+    #     {"format": "last-f", "confidence": "medium"},
+    #     {"format": "l.first", "confidence": "medium"},
+    #     {"format": "last_f", "confidence": "medium"},
+    #     {"format": "first.middle.last", "confidence": "medium"},
+    #     {"format": "first-last", "confidence": "medium"},
+    #     {"format": "last.f", "confidence": "medium"},
+    #     {"format": "last_first", "confidence": "medium"},
+    #     {"format": "f-last", "confidence": "medium"},
+    #     {"format": "first.l", "confidence": "medium"},
+    #     {"format": "first-l", "confidence": "medium"},
+    #     {"format": "first_l", "confidence": "medium"},
+    #     {"format": "first_last", "confidence": "medium"},
+    #     {"format": "f_last", "confidence": "medium"},
+    #     {"format": "last-first", "confidence": "medium"},
+    #     {"format": "flast", "confidence": "medium"},
+    #     {"format": "lastf", "confidence": "medium"},
+    #     {"format": "l_first", "confidence": "medium"},
+    #     {"format": "l-first", "confidence": "medium"},
+    #     {"format": "first-middle-last", "confidence": "low"},
+    #     {"format": "firstmlast", "confidence": "low"},
+    #     {"format": "last.middle.first", "confidence": "low"},
+    #     {"format": "last_middle_first", "confidence": "low"},
+    #     {"format": "first_middle_last", "confidence": "low"},
+    #     {"format": "last-middle-first", "confidence": "low"},
+    #     {"format": "first-m-last", "confidence": "low"},
+    #     {"format": "firstmiddlelast", "confidence": "low"},
+    #     {"format": "last.m.first", "confidence": "low"},
+    #     {"format": "lastmfirst", "confidence": "low"},
+    #     {"format": "lastmiddlefirst", "confidence": "low"},
+    #     {"format": "last_m_first", "confidence": "low"},
+    #     {"format": "first.m.last", "confidence": "low"},
+    #     {"format": "first_m_last", "confidence": "low"},
+    #     {"format": "last-m-first", "confidence": "low"}
+    #   ]
+    # }
+    def find_domain(domain: '', company_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"
+      elsif !(domain.nil? || domain.empty?) && !(company_name.nil? || company_name.empty?)
+        raise ArgumentError, "Only one of domain or company_name can be provided"
       end
 
+      params = {}
+      params[:domain] = domain unless domain.nil? || domain.empty?
+      params[:company_name] = company_name unless company_name.nil? || company_name.empty?
+
       @@request.get('guessformat', params)
     end
 

data/zerobounce.gemspec

@@ -29,6 +29,8 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.add_dependency 'rest-client', '~>2.1'
   spec.add_dependency 'dotenv'
 
+  spec.add_development_dependency 'base64' # stdlib gem on Ruby 3.4+
+  spec.add_development_dependency 'bigdecimal' # required by crack (webmock) on Ruby 3.4+
   spec.add_development_dependency 'bundler', '~> 2.4.6'
   spec.add_development_dependency 'pry', '~> 0.14.1'
   spec.add_development_dependency 'rake', '~> 13.0'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: zerobounce-sdk
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 2.0.13
 platform: ruby
 authors:
 - Zero Bounce
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-08-28 00:00:00.000000000 Z
+date: 2026-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -38,6 +37,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  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: bigdecimal
+  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
@@ -233,36 +260,44 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".env.sample"
+- ".env.example"
+- ".github/auto_assign.yml"
+- ".github/workflows/auto_assign_ci.yaml"
+- ".github/workflows/codeql.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
-- documentation_es.md
 - files/scoring.csv
 - files/validation.csv
 - files/zerobounce-ai-scoring.csv
 - files/zerobounce-batch-validation.csv
 - lib/zerobounce.rb
+- lib/zerobounce/api_urls.rb
 - lib/zerobounce/base_request.rb
 - lib/zerobounce/configuration.rb
 - lib/zerobounce/error.rb
 - lib/zerobounce/mock_request.rb
 - lib/zerobounce/request.rb
+- lib/zerobounce/validate_status.rb
+- lib/zerobounce/validate_sub_status.rb
 - lib/zerobounce/version.rb
 - zerobounce.gemspec
 homepage: https://zerobounce.net
@@ -270,7 +305,6 @@ licenses:
 - MIT
 metadata:
   yard.run: yri
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -285,8 +319,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
-signing_key: 
+rubygems_version: 3.6.6
 specification_version: 4
 summary: A Ruby client for Zerobounce.net.
 test_files: []

data/.env.sample

@@ -1,3 +0,0 @@
-ZEROBOUNCE_API_KEY=99e7ef20ceea4480a173b07b1be75371
-INCORRECT_API_KEY=thiskeyisinvalidorotherwiseincorrect
-TEST=unit