zerobounce-sdk 1.2.0 → 2.1.0

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."}
 ```
 
@@ -496,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/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/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
 
@@ -41,6 +42,11 @@ 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.bulk_post(path, params, content_type='application/json', filepath=nil)
       response = self._post(Zerobounce.configuration.bulk_api_root_url, path, params, \
           content_type, filepath)

data/lib/zerobounce/request.rb

@@ -2,6 +2,7 @@
 
 require 'stringio'
 require 'zerobounce/base_request'
+require 'zerobounce/get_file_helper'
 
 module Zerobounce
 
@@ -47,6 +48,12 @@ 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.bulk_post(path, params, content_type='application/json', filepath=nil)
       response = self._post(Zerobounce.configuration.bulk_api_root_url, path, params, \
           content_type, filepath)

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.2.0'
+  VERSION = '2.1.0'
 end

data/lib/zerobounce.rb

@@ -2,9 +2,15 @@
 # frozen_string_literal: true
 
 require 'date'
+require 'tempfile'
 
 require 'zerobounce/error'
 require 'zerobounce/version'
+require 'zerobounce/download_type'
+require 'zerobounce/get_file_options'
+require 'zerobounce/get_file_helper'
+require 'zerobounce/validate_status'
+require 'zerobounce/validate_sub_status'
 require 'zerobounce/request'
 require 'zerobounce/mock_request'
 require 'zerobounce/configuration'
@@ -26,6 +32,14 @@ module Zerobounce
     end
     alias config configuration
 
+    # Whether a getfile response body looks like a JSON error payload (including HTTP 200).
+    #
+    # @param [String] body
+    # @return [Boolean]
+    def get_file_json_indicates_error?(body)
+      GetFileHelper.json_indicates_error?(body)
+    end
+
     # Configure Zerobounce inside a block.
     #
     # @example
@@ -133,10 +147,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"
     # }
@@ -241,7 +258,8 @@ module Zerobounce
         last_name_column: 3,
         gender_column: 4,
         has_header_row: true,
-        return_url: nil
+        return_url: nil,
+        allow_phase_2: nil
       )
       params = {
         email_address_column: email_address_column,
@@ -251,9 +269,34 @@ module Zerobounce
       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
+      unless allow_phase_2.nil?
+        params[:allow_phase_2] = allow_phase_2 ? 'true' : 'false'
+      end
       @@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
+    # @option [Boolean] :allow_phase_2 When set, sends allow_phase_2 (validation bulk only).
+    # @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.
@@ -277,13 +320,20 @@ module Zerobounce
 
     # Get validate results file
     #
-    # @param [String] :file_id Id of the file.
-    #
-    # @return [String/File?]
-    def validate_file_get(file_id)
-      # todo:
-      params = {file_id: file_id}
-      @@request.bulk_get('getfile', params)
+    # @param [String] file_id Id of the file.
+    # @param [Zerobounce::GetFileOptions, nil] options Optional +download_type+ and +activity_data+ (validation bulk only).
+    #
+    # @return [String] file body on success
+    # @raise [RuntimeError] on API/JSON error responses
+    def validate_file_get(file_id, options = nil)
+      params = { file_id: file_id }
+      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'
+        end
+      end
+      @@request.bulk_getfile('getfile', params)
     end
 
     # Delete validate file
@@ -331,15 +381,37 @@ module Zerobounce
       @@request.bulk_post('scoring/sendfile', params, 'multipart/form-data', filepath)
     end
 
-    # Get validate results file
+    # 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 scoring bulk results file
     #
-    # @param [String] :file_id Id of the file.
+    # @param [String] file_id Id of the file.
+    # @param [Zerobounce::GetFileOptions, nil] options Optional +download_type+; +activity_data+ is not sent.
     #
-    # @return [String/File?]
-    def scoring_file_get(file_id)
-      # todo:
-      params = {file_id: file_id}
-      @@request.bulk_get('scoring/getfile', params)
+    # @return [String] file body on success
+    # @raise [RuntimeError] on API/JSON error responses
+    def scoring_file_get(file_id, options = nil)
+      params = { file_id: file_id }
+      if options && options.download_type
+        params[:download_type] = options.download_type
+      end
+      @@request.bulk_getfile('scoring/getfile', params)
     end
 
     # Get validate file status
@@ -425,6 +497,8 @@ module Zerobounce
     #    ]
     # }
     def guessformat(domain, first_name: '', middle_name: '', last_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?

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'