verifalia 1.2.0 → 2.1.0

data/lib/verifalia/client.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Verifalia - Email list cleaning and real-time email verification service
+# https://verifalia.com/
+# support@verifalia.com
+#
+# Copyright (c) 2005-2024 Cobisi Research
+#
+# Cobisi Research
+# Via Della Costituzione, 31
+# 35010 Vigonza
+# Italy - European Union
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'openssl/x509'
+require_relative './rest/client'
+
+module Verifalia
+  # HTTPS-based REST client for Verifalia.
+  class Client
+    # The version of the Verifalia SDK for Ruby.
+    VERSION = '2.1.0'
+
+    # Allows to verify email addresses and manage email verification jobs using the Verifalia service.
+    attr_reader :email_validations
+
+    # Manages credit packs, daily free credits and usage consumption for the Verifalia account.
+    attr_reader :credits
+
+    # Initializes a new HTTPS-based REST client for Verifalia with the specified options.
+    #
+    # While authenticating with your Verifalia main account credentials is possible, it is strongly advised to create
+    # one or more users (formerly known as sub-accounts) with just the required permissions, for improved security.
+    # To create a new user or manage existing ones, please visit 'https://verifalia.com/client-area#/users'
+    #
+    # @param [nil] authenticator A custom authenticator the client will use to authenticate against the Verifalia API.
+    # @param [nil] username The user-name used to authenticate against the Verifalia API using basic auth.
+    # @param [nil] password The password used to authenticate against the Verifalia API using basic auth.
+    # @param [nil] ssl_client_cert The X.509 client certificate used to authenticate against the Verifalia API using mutual TLS authentication. Available to premium Verifalia plans only.
+    # @param [nil] ssl_client_key The private key used to authenticate against the Verifalia API using mutual TLS authentication. Available to premium Verifalia plans only.
+    # @param [nil] base_urls Alternative base URLs to use while connecting against the Verifalia API.
+    # @param [nil] logger A logger where to write diagnostics messages, useful while debugging.
+    def initialize(authenticator: nil, username: nil, password: nil, ssl_client_cert: nil, ssl_client_key: nil, base_urls: nil, logger: nil)
+      @base_urls = base_urls
+
+      # Initialize the authenticator this client will use while connecting to the Verifalia API
+
+      if !authenticator.nil?
+        @authenticator = authenticator
+      elsif !username.nil?
+        @authenticator = Verifalia::Security::UsernamePasswordAuthenticator.new(username, password)
+      elsif !ssl_client_cert.nil?
+        @authenticator = Verifalia::Security::CertificateAuthenticator.new(ssl_client_cert, ssl_client_key)
+        @base_urls ||= Verifalia::Rest::BASE_CCA_URLS
+      else
+        raise ArgumentError, 'Username is nil and no other authentication method was specified: please visit https://verifalia.com/client-area to set up a new user, if you don\'t have one.'
+      end
+
+      @base_urls ||= Verifalia::Rest::BASE_URLS
+      @rest_client = Verifalia::Rest::Client.new(@authenticator,
+                                                 "verifalia-rest-client/ruby/#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}/#{VERSION}",
+                                                 @base_urls)
+
+      @rest_client.logger = logger
+
+      # Initialize the underlying resource clients
+
+      @email_validations = Verifalia::EmailValidations::Client.new(@rest_client)
+      @credits = Verifalia::Credits::Client.new(@rest_client)
+    end
+  end
+end

data/lib/verifalia/credits/balance.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Verifalia - Email list cleaning and real-time email verification service
+# https://verifalia.com/
+# support@verifalia.com
+#
+# Copyright (c) 2005-2024 Cobisi Research
+#
+# Cobisi Research
+# Via Della Costituzione, 31
+# 35010 Vigonza
+# Italy - European Union
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Verifalia
+  module Credits
+    # The credits balance for the Verifalia account.
+    class Balance
+      # The number of credit packs (that is, non-expiring credits) available for the account.
+      attr_reader :credit_packs
+
+      # The number of free daily credits of the account, where available.
+      attr_reader :free_credits
+
+      # A string representing the amount of time before the daily credits expire, where available, expressed in the form +hh:mm:ss+.
+      attr_reader :free_credits_reset_in
+
+      def initialize(credit_packs, free_credits, free_credits_reset_in)
+        @credit_packs = credit_packs
+        @free_credits = free_credits
+        @free_credits_reset_in = free_credits_reset_in
+      end
+
+      # Parse a Balance from a JSON string.
+      def self.from_json(data)
+        Balance.new data['creditPacks'],
+                    data['freeCredits'],
+                    data['freeCreditsResetIn']
+      end
+    end
+  end
+end

data/lib/verifalia/credits/client.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Verifalia - Email list cleaning and real-time email verification service
+# https://verifalia.com/
+# support@verifalia.com
+#
+# Copyright (c) 2005-2024 Cobisi Research
+#
+# Cobisi Research
+# Via Della Costituzione, 31
+# 35010 Vigonza
+# Italy - European Union
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'balance'
+
+module Verifalia
+  module Credits
+    # Manages credit packs, daily free credits and usage consumption for the Verifalia account.
+    class Client
+      def initialize(rest_client)
+        @rest_client = rest_client
+      end
+
+      # Returns the current credits balance for the Verifalia account.
+      # @return [Verifalia::Credits::Balance] The account balance.
+      def get_balance
+        response = @rest_client.invoke 'get',
+                                       'credits/balance'
+
+        return Balance.from_json(JSON.parse(response.body)) if response.status == 200
+
+        raise "Unexpected HTTP response: #{response.status} #{response.body}"
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/client.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+# Verifalia - Email list cleaning and real-time email verification service
+# https://verifalia.com/
+# support@verifalia.com
+#
+# Copyright (c) 2005-2024 Cobisi Research
+#
+# Cobisi Research
+# Via Della Costituzione, 31
+# 35010 Vigonza
+# Italy - European Union
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'net/http'
+require_relative 'job'
+require_relative 'overview'
+require_relative 'entry'
+require_relative 'wait_options'
+require_relative 'request'
+require_relative 'request_entry'
+require_relative 'completion_callback'
+
+module Verifalia
+  module EmailValidations
+    # Allows to verify email addresses and manage email verification jobs using the Verifalia service.
+    class Client
+      def initialize(rest_client)
+        @rest_client = rest_client
+      end
+
+      # Submits a new email validation for processing.
+      #
+      # By default, this method waits for the completion of the email validation job: pass a +WaitOptions+ to request
+      # a different waiting behavior.
+      #
+      # @param data The input data to verify.
+      # @param [nil] quality The desired results quality for this email validation.
+      # @param [nil] priority
+      # @param [nil] deduplication An optional string with the name of the algorithm our engine will use to scrub the list of email addresses and remove its duplicates. The following values are currently supported: +Off+ does not mark duplicated email addresses, +Safe+ mark duplicated email addresses with an algorithm which guarantees no false duplicates are returned, +Relaxed+ mark duplicated email addresses using a set of relaxed rules which assume the target email service providers are configured with modern settings only. If not specified, Verifalia will not mark duplicated email addresses.
+      # @param [nil] name An optional user-defined name for the validation job, for your own reference.
+      # @param [nil] retention An optional string with the desired data retention period to observe for the validation job, expressed in the format +dd.hh:mm:ss+ (where +dd.+ days, +hh:+ hours, +mm:+ minutes, +ss:+ seconds); the initial +dd.+ part is added only for periods of more than 24 hours. The value has a minimum of 5 minutes (+0:5:0+) and a maximum of 30 days (+30.0:0:0+): Verifalia will delete the job and its data once its data retention period is over, starting to count when it gets completed. If not specified, Verifalia falls back to the configured data retention period of the submitting user / browser app and, should it be unset, to the configured data retention period of the Verifalia account, with a default of 30 days.
+      # @param [nil] completion_callback An optional hash describing the desired completion callback behavior, with the following keys: +url+ A string with the URL Verifalia will invoke once the job results are ready. See how to handle completion callbacks. +version+ An optional string which defines the callback schema our dispatcher must obey when invoking the provided callback URL. Valid values are: +1.0+ the callback includes the completed job ID. +1.1+ everything included with +1.0+ plus the job name. If not specified, Verifalia will use the most recent schema available at the time the used API version was released. +skipServerCertificateValidation+ An optional boolean which allows to skip the server certificate validation for the external callback server, useful for testing purposes at development time when the callback server is using a self-signed certificate.
+      # @param [nil] wait_options The options which rule out how to wait for the completion of the email validation.
+      # @return [Verifalia::EmailValidations::Job] The submitted validation job (or +nil+ if expired / deleted while waiting for its completion).
+      def submit(data,
+                 quality: nil,
+                 priority: nil,
+                 deduplication: nil,
+                 name: nil,
+                 retention: nil,
+                 completion_callback: nil,
+                 wait_options: nil)
+        # Determine how to handle the submission, based on the type of the argument
+
+        if data.nil?
+          raise ArgumentError, 'data can\'t be nil.'
+        elsif data.is_a?(String)
+          data = Request.new [(RequestEntry.new data)],
+                             quality: quality
+        elsif data.is_a? Enumerable
+          entries = data.map do |entry|
+            case entry
+            when String
+              # data is an Array[String]
+              RequestEntry.new entry.to_s
+            when RequestEntry
+              # data is an Array[RequestEntry]
+              entry
+            when Hash
+              # data is an Array[{ :inputData, :custom }]
+
+              raise ArgumentError, 'Input hash must have an :inputData key.' unless entry.key?(:input_data)
+
+              RequestEntry.new entry[:input_data], entry[:custom]
+            else
+              raise ArgumentError, 'Cannot map input data.'
+            end
+          end
+
+          data = Request.new entries,
+                             quality: quality
+        elsif data.is_a?(RequestEntry)
+          data = Request.new data,
+                             quality: quality
+        elsif !data.is_a?(Request)
+          raise ArgumentError, "Unsupported data type #{data.class}"
+        end
+
+        # Completion callback
+
+        if completion_callback.is_a?(Hash)
+          completion_callback = Verifalia::EmailValidations::CompletionCallback.new(completion_callback['url'],
+                                                                                    completion_callback['version'],
+                                                                                    completion_callback['skip_server_certificate_validation'])
+        end
+
+        # Send the request to the Verifalia API
+
+        wait_options_or_default = wait_options.nil? ? WaitOptions.default : wait_options
+
+        payload = {
+          entries: data.entries.map do |entry|
+            {
+              inputData: entry.input_data,
+              custom: entry.custom
+            }
+          end,
+          quality: quality,
+          priority: priority,
+          deduplication: deduplication,
+          name: name,
+          retention: retention,
+          callback: (
+            unless completion_callback.nil?
+              {
+                url: completion_callback&.url,
+                version: completion_callback&.version,
+                skipServerCertificateValidation: completion_callback&.skip_server_certificate_validation
+              }
+            end
+          )
+        }.compact.to_json
+
+        response = @rest_client.invoke 'post',
+                                       "email-validations?waitTime=#{wait_options_or_default.submission_wait_time}",
+                                       {
+                                         body: payload,
+                                         headers:
+                                           {
+                                             'Content-Type': 'application/json',
+                                             'Accept': 'application/json'
+                                           }
+                                       }
+
+        if response.status == 202 || response.status == 200
+          job = Job.from_json(JSON.parse(response.body))
+
+          return job if wait_options_or_default == WaitOptions.no_wait || response.status == 200
+
+          return get(job.overview.id, wait_options: wait_options_or_default)
+        end
+
+        raise "Unexpected HTTP response: #{response.status} #{response.body}"
+      end
+
+      # Returns an email validation job previously submitted for processing.
+      #
+      # By default, this method waits for the completion of the email validation job: pass a +WaitOptions+ to request
+      # a different waiting behavior.
+      # @param [String] id The ID of the email validation job to retrieve.
+      # @param [nil] wait_options The options which rule out how to wait for the completion of the email validation.
+      # @return [Verifalia::EmailValidations::Job] The fetched validation job (or +nil+ if not found).
+      def get(id, wait_options: nil)
+        wait_options_or_default = wait_options.nil? ? WaitOptions.default : wait_options
+
+        loop do
+          response = @rest_client.invoke 'get',
+                                         "email-validations/#{id}?waitTime=#{wait_options_or_default.poll_wait_time}"
+
+          return nil if response.status == 404 || response.status == 410
+
+          unless response.status == 202 || response.status == 200
+            raise "Unexpected HTTP response: #{response.status} #{response.body}"
+          end
+
+          job = Job.from_json(JSON.parse(response.body))
+
+          return job if wait_options_or_default == WaitOptions.no_wait || response.status == 200
+
+          # Fires a progress, since we are not yet completed
+
+          wait_options.progress&.call(job.overview)
+
+          # Wait for the next polling schedule
+
+          wait_options.wait_for_next_poll(job)
+        end
+      end
+
+      # Exports the validated entries for a completed email validation job, using the specified output format.
+      # See +ExportedEntriesFormat+ for a list of the values supported at the time this SDK has been released.
+      #
+      # Supported formats:
+      # - Comma-Separated Values (CSV)
+      # - Microsoft Excel (.xlsx)
+      # - Microsoft Excel 97-2003 (.xls)
+      #
+      # @param [String] id The ID of the email validation job to retrieve.
+      # @param [String] format The MIME content type of the desired output file format.
+      # @return [String] The exported data.
+      def export(id, format)
+        response = @rest_client.invoke 'get',
+                                       "email-validations/#{id}/entries",
+                                       {
+                                         headers:
+                                           {
+                                             'Accept': format
+                                           }
+                                       }
+
+        return nil if response.status == 404 || response.status == 410
+        return response.body if response.status == 200
+
+        raise "Unexpected HTTP response: #{response.status} #{response.body}"
+      end
+
+      # Deletes an email validation job previously submitted for processing.
+      # @param [String] id The ID of the email validation job to delete.
+      def delete(id)
+        response = @rest_client.invoke 'delete',
+                                       "email-validations/#{id}"
+
+        return if response.status == 200 || response.status == 410
+
+        raise "Unexpected HTTP response: #{response.status} #{response.body}"
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/completion_callback.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Verifalia - Email list cleaning and real-time email verification service
+# https://verifalia.com/
+# support@verifalia.com
+#
+# Copyright (c) 2005-2024 Cobisi Research
+#
+# Cobisi Research
+# Via Della Costituzione, 31
+# 35010 Vigonza
+# Italy - European Union
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Verifalia
+  module EmailValidations
+    class CompletionCallback
+      attr_accessor :url, :version, :skip_server_certificate_validation
+
+      def initialize(url, version = nil, skip_server_certificate_validation = false)
+        @url = url
+        @version = version
+        @skip_server_certificate_validation = skip_server_certificate_validation
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/entry.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Verifalia - Email list cleaning and real-time email verification service
+# https://verifalia.com/
+# support@verifalia.com
+#
+# Copyright (c) 2005-2024 Cobisi Research
+#
+# Cobisi Research
+# Via Della Costituzione, 31
+# 35010 Vigonza
+# Italy - European Union
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Verifalia
+  module EmailValidations
+    # Represents a single validated entry within a job.
+    class Entry
+      # The input string being validated.
+      attr_reader :input_data
+
+      # The classification for the status of this email address. See +EntryClassification+ for a list of the values
+      # supported at the time this SDK has been released.
+      attr_reader :classification
+
+      # The validation status for this entry. See +EntryStatus+ for a list of the values supported at the time this SDK
+      # has been released.
+      attr_reader :status
+
+      # Gets the email address, without any eventual comment or folding white space. Returns +nil+ if the input data
+      # is not a syntactically invalid e-mail address.
+      attr_reader :email_address
+
+      # Gets the local part of the email address, without comments and folding white spaces.
+      attr_reader :email_address_local_part
+
+      # Gets the domain part of the email address, without comments and folding white spaces.
+      #
+      # If the ASCII-only (punycode) version of the domain part is needed, use +@ascii_email_address_domain_part+.
+      attr_reader :email_address_domain_part
+
+      # Gets the domain part of the email address, converted to ASCII if needed using the punycode algorithm and with
+      # comments and folding white spaces stripped off.
+      #
+      # If the non-punycode version of the domain part is needed, use +@email_address_domain_part+.
+      attr_reader :ascii_email_address_domain_part
+
+      # If +true+, the email address has an international mailbox name.
+      attr_reader :has_international_mailbox_name
+
+      # If +true+, the email address has an international domain name.
+      attr_reader :has_international_domain_name
+
+      # If +true+, the email address comes from a disposable email address (DEA) provider.
+      #
+      # See https://verifalia.com/help/email-validations/what-is-a-disposable-email-address-dea for additional information
+      # about disposable email addresses.
+      attr_reader :is_disposable_email_address
+
+      # If +true+, the local part of the email address is a well-known role account.
+      attr_reader :is_role_account
+
+      # If +true+, the email address comes from a free email address provider (e.g. gmail, yahoo, outlook / hotmail, ...).
+      attr_reader :is_free_email_address
+
+      # The position of the character in the email address that eventually caused the syntax validation to fail.
+      attr_reader :syntax_failure_index
+
+      # The user-defined, optional string which is passed back upon completing the validation.
+      attr_reader :custom
+
+      # The zero-based index of the first occurrence of this email address in the parent +Job+, in the event the +status+
+      # for this entry is +Duplicate+; duplicated items do not expose any result detail apart from this and the eventual
+      # +custom+ values.
+      attr_reader :duplicate_of
+
+      # The date this entry has been completed, if available.
+      attr_reader :completed_on
+
+      # The potential corrections for the input data, in the event Verifalia identified potential typos during the verification process.
+      attr_reader :suggestions
+
+      def initialize (input_data, classification, status, email_address, email_address_local_part, email_address_domain_part,
+                      has_international_mailbox_name, has_international_domain_name, is_disposable_email_address, is_role_account,
+                      is_free_email_address, syntax_failure_index, custom, duplicate_of, completed_on, ascii_email_address_domain_part,
+                      suggestions)
+        @input_data = input_data
+        @classification = classification
+        @status = status
+        @email_address = email_address
+        @email_address_local_part = email_address_local_part
+        @email_address_domain_part = email_address_domain_part
+        @has_international_mailbox_name = has_international_mailbox_name
+        @has_international_domain_name = has_international_domain_name
+        @is_disposable_email_address = is_disposable_email_address
+        @is_role_account = is_role_account
+        @is_free_email_address = is_free_email_address
+        @syntax_failure_index = syntax_failure_index
+        @custom = custom
+        @duplicate_of = duplicate_of
+        @completed_on = completed_on
+        @ascii_email_address_domain_part = ascii_email_address_domain_part
+        @suggestions = suggestions
+      end
+    end
+  end
+end

data/lib/verifalia/email_validation/entry_classification.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Verifalia - Email list cleaning and real-time email verification service
+# https://verifalia.com/
+# support@verifalia.com
+#
+# Copyright (c) 2005-2024 Cobisi Research
+#
+# Cobisi Research
+# Via Della Costituzione, 31
+# 35010 Vigonza
+# Italy - European Union
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Verifalia
+  module EmailValidations
+    # Provides values for the supported validation statuses for a job +entry+.
+    module EntryClassification
+      # An +entry+ marked as +Deliverable+ refers to an email which is deliverable.
+      DELIVERABLE = 'Deliverable'
+
+      # An +entry+ marked as +Risky+ refers to an email which could be no longer valid.
+      RISKY = 'Risky'
+
+      # An +entru+ marked as +Undeliverable+ refers to an email which is either invalid or no longer deliverable.
+      UNDELIVERABLE = 'Undeliverable'
+
+      # An +entry+ marked as +Unknown+ contains an email address whose deliverability is unknown.
+      UNKNOWN = 'Unknown'
+    end
+  end
+end