zerobounce-sdk 1.1.1 → 2.1.8

data/documentation.md

@@ -76,10 +76,13 @@ Zerobounce.api_usage(Date.today, Date.today)
  "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"=>"4/28/2023",
  "end_date"=>"4/28/2023"}
 ```
@@ -265,10 +268,13 @@ Send file
     last_name_column: 3,
     gender_column: 4,
     has_header_row: true,
-    return_url: nil         ### results callback url
+    return_url: nil,        ### results callback url
+    allow_phase_2: true     ### optional; validation bulk sendfile only (omit or nil to skip)
  ### Zerobounce.validate_file_send(validate_file_path, email_address_column: 1, gender_column: 4)
 ```
 
+Bulk validation uses `https://bulkapi.zerobounce.net/v2`. See [v2 send file](https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-send-file), [v2 file status](https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-file-status), and [v2 get file](https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-get-file).
+
 Check file
 ```ruby
 file_id = "75d854a6-565c-49f9-b4c8-b3344480ec4c"
@@ -281,6 +287,7 @@ Zerobounce.validate_file_check(file_id)
  "upload_date"=>"2023-04-28T15:25:41Z",
  "file_status"=>"Greylisted",
  "complete_percentage"=>"0%",
+ "file_phase_2_status"=>"N/A",  ### when present (validation bulk v2)
  "error_reason"=>nil,
  "return_url"=>nil}
 ```
@@ -293,6 +300,16 @@ Zerobounce.validate_file_get(file_id)
 => "\"email\",\"first\",\"last\",\"gender\",\"ip\",\"ZB Status\",\"ZB Sub Status\",\"ZB Account\",\"ZB Domain\",\"ZB First Name\",\"ZB Last Name\",\"ZB Gender\",\"ZB Free Email\",\"ZB MX Found\",\"ZB MX Record\",\"ZB SMTP Provider\",\"ZB Did You Mean\"\n\"disposable@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"disposable\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"invalid@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"mailbox_not_found\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"valid@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"valid\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"toxic@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"toxic\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"donotmail@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"role_based\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"spamtrap@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"spamtrap\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"abuse@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"abuse\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"unknown@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"mail_server_temporary_error\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"catch_all@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"catch-all\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"antispam_system@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"antispam_system\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"does_not_accept_mail@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"does_not_accept_mail\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"exception_occurred@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"exception_occurred\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"failed_smtp_connection@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"failed_smtp_connection\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"failed_syntax_check@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"failed_syntax_check\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"forcible_disconnect@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"forcible_disconnect\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"global_suppression@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"global_suppression\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"greylisted@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"greylisted\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"leading_period_removed@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"valid\",\"leading_period_removed\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mail_server_did_not_respond@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"mail_server_did_not_respond\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mail_server_temporary_error@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"mail_server_temporary_error\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mailbox_quota_exceeded@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"mailbox_quota_exceeded\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mailbox_not_found@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"mailbox_not_found\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"no_dns_entries@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"no_dns_entries\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"possible_trap@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"possible_trap\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"possible_typo@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"possible_typo\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"role_based@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"role_based\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"timeout_exceeded@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"timeout_exceeded\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"unroutable_ip_address@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"unroutable_ip_address\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"free_email@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"valid\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"True\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"role_based_catch_all@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"role_based_catch_all\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n"
 ```
 
+Optional [v2 get file](https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-get-file) query parameters: `Zerobounce::GetFileOptions` and `Zerobounce::DownloadType` (`PHASE_1`, `PHASE_2`, `COMBINED`). Use `activity_data` on the options for validation `validate_file_get` only. JSON error bodies (including some HTTP 200 responses) raise `RuntimeError`; use `Zerobounce.get_file_json_indicates_error?(body)` on a raw string if needed.
+
+```ruby
+opts = Zerobounce::GetFileOptions.new(
+  download_type: Zerobounce::DownloadType::COMBINED,
+  activity_data: true
+)
+csv = Zerobounce.validate_file_get(file_id, opts)
+```
+
 Delete file
 ```ruby
 file_id = "75d854a6-565c-49f9-b4c8-b3344480ec4c"
@@ -346,13 +363,14 @@ file_id = "89fb7262-b845-4fa1-aa25-e486347ec64e"
 => "89fb7262-b845-4fa1-aa25-e486347ec64e"
 Zerobounce.scoring_file_get(file_id)
 => "\"email\",\"ZeroBounceQualityScore\"\r\n\"disposable@example.com\",\"0\"\r\n\"invalid@example.com\",\"10\"\r\n\"valid@example.com\",\"10\"\r\n\"toxic@example.com\",\"2\"\r\n\"donotmail@example.com\",\"0\"\r\n\"spamtrap@example.com\",\"0\"\r\n\"abuse@example.com\",\"10\"\r\n\"unknown@example.com\",\"10\"\r\n\"catch_all@example.com\",\"10\"\r\n\"antispam_system@example.com\",\"0\"\r\n\"does_not_accept_mail@example.com\",\"0\"\r\n\"exception_occurred@example.com\",\"0\"\r\n\"failed_smtp_connection@example.com\",\"0\"\r\n\"failed_syntax_check@example.com\",\"0\"\r\n\"forcible_disconnect@example.com\",\"0\"\r\n\"global_suppression@example.com\",\"0\"\r\n\"greylisted@example.com\",\"0\"\r\n\"leading_period_removed@example.com\",\"0\"\r\n\"mail_server_did_not_respond@example.com\",\"0\"\r\n\"mail_server_temporary_error@example.com\",\"0\"\r\n\"mailbox_quota_exceeded@example.com\",\"0\"\r\n\"mailbox_not_found@example.com\",\"0\"\r\n\"no_dns_entries@example.com\",\"0\"\r\n\"possible_trap@example.com\",\"0\"\r\n\"possible_typo@example.com\",\"0\"\r\n\"role_based@example.com\",\"0\"\r\n\"timeout_exceeded@example.com\",\"0\"\r\n\"unroutable_ip_address@example.com\",\"0\"\r\n\"free_email@example.com\",\"0\"\r\n\"role_based_catch_all@example.com\",\"0\""
+### Optional second argument: GetFileOptions with download_type only (activity_data is not sent for scoring getfile)
 ```
 
 Delete file
 ```ruby
 file_id = "89fb7262-b845-4fa1-aa25-e486347ec64e"
 => "89fb7262-b845-4fa1-aa25-e486347ec64e"
-Zerobounce.validate_file_delete(file_id)
+Zerobounce.scoring_file_delete(file_id)
 => {"success"=>false, "message"=>"File cannot be found."}
 ```
 
@@ -400,6 +418,81 @@ Zerobounce.guessformat("zerobounce.net")
 # Zerobounce.guessformat("zerobounce.net", first_name: "John", middle_name: 'Deere', last_name: "Doe")
 ```
 
+Find Email Address
+```ruby
+Zerobounce.find_email("John", domain: "zerobounce.net")
+=>
+{
+  "email": "john@zerobounce.net",
+  "email_confidence": "medium",
+  "domain": "zerobounce.net",
+  "company_name": "ZeroBounce",
+  "did_you_mean": "",
+  "failure_reason": ""
+}
+
+# With additional name information for better accuracy
+Zerobounce.find_email("John", domain: "zerobounce.net", middle_name: "Deere", last_name: "Doe")
+```
+
+Find Domain Information
+```ruby
+Zerobounce.find_domain(domain: "zerobounce.net")
+=>
+{
+  "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"}
+  ]
+}
+```
+
 
 #### Development
 
@@ -421,17 +514,17 @@ Finished in 6.81 seconds (files took 0.40587 seconds to load)
 
 ##### Test parameters
 The tests use the following environment parameters:
-TEST {unit|live} influences whether mocked unit tests are run or the live server is used (credits may be used if you choose to do this)
-ZEROBOUNCE_API_KEY {<zerobounce-api-key-value>} this key is used to make requests to the live server; it is also used in mock tests as a valid key sample (any value will work for mock tests)
-INCORRECT_API_KEY {any non whitespace string value that is not a valid key} used for tests where the requests are meant to fail due to the API key value.
+- **TEST** {unit|live} – Influences whether mocked unit tests are run or the live server is used (credits may be used if you choose to do this).
+- **ZEROBOUNCE_API_KEY** – Your API key; used to make requests to the live server and in mock tests as the valid key sample (any value will work for mock tests).
+
+An invalid API key for error-handling tests is hardcoded in the spec; no env var is required.
 
-To set them
+To set them:
 ```bash
-export ZEROBOUNCE_API_KEY=99e7ef20ceea4480a173b07b1be75371
-export INCORRECT_API_KEY=thiskeyisinvalidorotherwiseincorrect
+export ZEROBOUNCE_API_KEY=your_api_key_here
 export TEST=unit
 ```
 
-A .env.sample file is provided.
+A .env.example file is provided.
 
-Mock tests were generated using webmock and vcr. This means that actual requests were made and recorded in the spec/cassettes with an (at the time) valid API key used for testing purposes. This key has been invalidated in the meantime, however it is provided in the .env.sample file for the mock tests to work. If you do not wish to use this key for mocks, you can replace it with any value in the .yml files under spec/cassettes or delete all of them and rerun the tests so that vcr records them with a new key.
+Mock tests were generated using webmock and vcr. This means that actual requests were made and recorded in the spec/cassettes with an (at the time) valid API key used for testing purposes. This key has been invalidated in the meantime, however it is provided in the .env.example file for the mock tests to work. If you do not wish to use this key for mocks, you can replace it with any value in the .yml files under spec/cassettes or delete all of them and rerun the tests so that vcr records them with a new key.

data/lib/zerobounce/api_urls.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  # API URL constants for Zerobounce endpoints
+  #
+  # This class provides constant values for different Zerobounce API endpoints
+  # that can be accessed publicly by gem users.
+  #
+  class ApiUrls
+    # API URLs
+    DEFAULT_URL = 'https://api.zerobounce.net/v2/'
+    EU_URL = 'https://api-eu.zerobounce.net/v2/'
+    US_URL = 'https://api-us.zerobounce.net/v2/'
+
+    # Bulk API URLs
+    BULK_DEFAULT_URL = 'https://bulkapi.zerobounce.net/v2/'
+  end
+end

data/lib/zerobounce/base_request.rb

@@ -13,6 +13,34 @@ module Zerobounce
 
     protected
 
+    # Strips trailing slashes from root URL without using a regex (avoids ReDoS).
+    def self.__root_without_trailing_slashes__(root)
+      s = root.to_s
+      s = s.chomp('/') while s.end_with?('/')
+      s
+    end
+
+    # Resolves and validates filepath to prevent path traversal (e.g. ../../etc/passwd).
+    # Returns a canonical path only if the file is under the current directory and is a regular file.
+    def self.__safe_file_path__(filepath)
+      raise ArgumentError, 'File path is required' if filepath.nil? || filepath.to_s.empty?
+      filepath = filepath.to_s
+      expanded = File.expand_path(filepath)
+      base = File.realpath(Dir.pwd)
+      base_with_sep = base + File::SEPARATOR
+      unless expanded == base || expanded.start_with?(base_with_sep)
+        raise ArgumentError, 'File path must be under the current directory'
+      end
+      canonical = File.realpath(expanded)
+      unless canonical == base || canonical.start_with?(base_with_sep)
+        raise ArgumentError, 'File path must be under the current directory'
+      end
+      unless File.file?(canonical)
+        raise ArgumentError, 'File path must point to a regular file'
+      end
+      canonical
+    end
+
     def self._get(root, path, params, content_type='application/json')
 
       # puts path
@@ -21,7 +49,7 @@ module Zerobounce
       raise ("API key must be assigned") if not Zerobounce.config.apikey
 
       params[:api_key] = Zerobounce.config.apikey
-      url = "#{root}/#{path}"
+      url = "#{Zerobounce::BaseRequest.__root_without_trailing_slashes__(root)}/#{path}"
 
       response = RestClient.get(url, {params: params})
       return response
@@ -32,11 +60,11 @@ module Zerobounce
       raise ("API key must be assigned") if not Zerobounce.config.apikey
 
       params[:api_key] = Zerobounce.config.apikey
-      url = "#{root}/#{path}"
+      url = "#{Zerobounce::BaseRequest.__root_without_trailing_slashes__(root)}/#{path}"
       response = nil
 
       if filepath or content_type == 'multipart/form-data'
-        params[:file] = File.new(filepath, 'rb')
+        params[:file] = File.new(Zerobounce::BaseRequest.__safe_file_path__(filepath), 'rb')
         params[:multipart] = true
         response = RestClient.post(url, params)
 

data/lib/zerobounce/configuration.rb

@@ -2,6 +2,7 @@
 
 require 'rest-client'
 require 'dotenv'
+require_relative 'api_urls'
 
 module Zerobounce
   # Configuration object for Zerobounce.
@@ -17,20 +18,23 @@ module Zerobounce
   # @attr [String] apikey
   #   A Zerobounce API key.
   #
+  # @attr [String] api_root_url
+  #   The Zerobounce API root URL. Defaults to ApiUrls::DEFAULT_URL.
+  #
+  # @attr [String] bulk_api_root_url
+  #   The Zerobounce bulk API root URL.
+  #
   # @attr [Array<Symbol>] valid_statues
   #   The statuses that are considered valid by {Response#valid?}.
   class Configuration
-    attr_accessor :host
-    attr_accessor :headers
-    attr_accessor :apikey
-    attr_accessor :valid_statuses
-    attr_accessor :mock
+    attr_accessor :headers, :apikey, :api_root_url, :bulk_api_root_url, :valid_statuses, :mock
 
-    def initialize(mock=false)
-      if File.file?(".env") then Dotenv.load(".env") else Dotenv.load end
-      self.host = 'https://api.zerobounce.net'
+    def initialize(mock = false)
+      File.file?('.env') ? Dotenv.load('.env') : Dotenv.load
       self.apikey = ENV['ZEROBOUNCE_API_KEY']
-      self.valid_statuses = %i[valid catch_all]
+      self.api_root_url = ENV['ZEROBOUNCE_API_URL'] || ApiUrls::DEFAULT_URL
+      self.bulk_api_root_url = ENV['ZEROBOUNCE_BULK_API_URL'] || ApiUrls::BULK_DEFAULT_URL
+      self.valid_statuses = %i[valid catch_all accept_all]
       self.headers = { user_agent: "ZerobounceRubyGem/#{Zerobounce::VERSION}" }
       self.mock = mock
     end

data/lib/zerobounce/download_type.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  # Values for bulk getfile query parameter +download_type+ (validation and scoring).
+  module DownloadType
+    PHASE_1 = 'phase_1'
+    PHASE_2 = 'phase_2'
+    COMBINED = 'combined'
+  end
+end

data/lib/zerobounce/get_file_helper.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'stringio'
+
+module Zerobounce
+  # Bulk getfile response handling (v2): HTTP errors, JSON error bodies (including HTTP 200).
+  module GetFileHelper
+    module_function
+
+    # @param [String] body
+    # @return [Boolean]
+    def json_indicates_error?(body)
+      t = body.to_s.lstrip
+      return false if t.empty? || t[0] != '{'
+
+      o = JSON.parse(t)
+      return false unless o.is_a?(Hash)
+
+      if o.key?('success')
+        s = o['success']
+        return true if s == false || s == 'False' || s == 'false'
+      end
+
+      %w[message error error_message].each do |k|
+        v = o[k]
+        next if v.nil?
+
+        return true if v.is_a?(String) && !v.strip.empty?
+        return true if v.is_a?(Array) && !v.empty?
+      end
+
+      o.key?('success')
+    rescue JSON::ParserError
+      false
+    end
+
+    # @param [String] body
+    # @return [String]
+    def format_error_message(body)
+      o = JSON.parse(body.to_s)
+      return body.to_s unless o.is_a?(Hash)
+
+      %w[message error error_message].each do |k|
+        v = o[k]
+        next if v.nil?
+        return v.strip if v.is_a?(String) && !v.strip.empty?
+        return v[0].strip if v.is_a?(Array) && v[0].is_a?(String)
+      end
+      body.to_s
+    rescue JSON::ParserError
+      body.to_s.empty? ? 'Invalid getfile response' : body.to_s
+    end
+
+    # @param [String] body
+    # @param [String] content_type
+    # @return [Boolean]
+    def should_treat_as_error?(body, content_type)
+      ct = content_type.to_s.downcase
+      return true if ct.include?('application/json')
+
+      json_indicates_error?(body)
+    end
+
+    # @param [RestClient::Response] response
+    # @return [String] CSV/text body on success
+    def process_getfile_response(response)
+      code = response.code.to_i
+      body_str = response.body.to_s
+      ct = (response.headers[:content_type] || response.headers['Content-Type'] || '').to_s
+
+      if code > 299
+        msg = if body_str.lstrip.start_with?('{')
+                format_error_message(body_str)
+              else
+                body_str.empty? ? "HTTP #{code}" : body_str
+              end
+        raise msg
+      end
+
+      if should_treat_as_error?(body_str, ct)
+        raise format_error_message(body_str)
+      end
+
+      io = StringIO.new(response.body)
+      io.set_encoding_by_bom
+      io.string
+    end
+  end
+end

data/lib/zerobounce/get_file_options.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Zerobounce
+  # Optional query parameters for bulk getfile.
+  # +activity_data+ applies to validation +validate_file_get+ only; scoring getfile does not send it.
+  class GetFileOptions
+    attr_accessor :download_type, :activity_data
+
+    def initialize(download_type: nil, activity_data: nil)
+      @download_type = download_type
+      @activity_data = activity_data
+    end
+  end
+end

data/lib/zerobounce/mock_request.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'zerobounce/base_request'
+require 'zerobounce/get_file_helper'
 
 module Zerobounce
 
@@ -8,7 +9,7 @@ module Zerobounce
   class MockRequest < 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)
@@ -25,7 +26,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)
@@ -41,8 +42,30 @@ module Zerobounce
       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 response.headers[:content_type] == 'application/json'
+        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::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/request.rb

@@ -2,6 +2,7 @@
 
 require 'stringio'
 require 'zerobounce/base_request'
+require 'zerobounce/get_file_helper'
 
 module Zerobounce
 
@@ -9,7 +10,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 +30,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)
@@ -47,8 +48,31 @@ module Zerobounce
       end
     end
 
+    # Bulk getfile only: treats non-2xx and JSON error payloads (including HTTP 200) as failures.
+    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 response.headers[:content_type] == 'application/json'
+        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::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.1'
+  VERSION = '2.1.8'
 end