loqate 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1480f53219de60b29e6137f502c3b5c09af4fc0b9f8737a8248d2e71704b391a
-  data.tar.gz: 7842ed023231d338d31ede50f77e87e3ddcfcf78131754539bb55e3d9744722f
+  metadata.gz: f33980e922897d782156083e90517425569e09426cc653d5812e8df8618b42fa
+  data.tar.gz: b8aaca5b1a67c7c0ed9fafa14956a348bdea44f0480ba5f0c8d9a9e3ffb81e67
 SHA512:
-  metadata.gz: 8e65821f932b0e0c2c910e0e92c02c4ab68cbde159db6e50ae645931c0497d3b87f0f4b37ada680f56feadb6a1302b3ea6d118fd4fbfa7c828b8484ad68b1aaf
-  data.tar.gz: a56f36319aa424b4fb368defd2bb03b76770d66faec41ebe5ac6efe8f9ffaef5edee87595c437a6f85269a7841a083adfc3ff6872d59500996021d0452143bc3
+  metadata.gz: 29926eba63928015dd96214ea4e7fe987b91521afa10415b74b866756d6da202fed82da9829417293fcd9910ecc875b1f2247eae019d3d9d3151576bb961e7a0
+  data.tar.gz: 02a4def39549a2c69583b1528e401e3712576e2b3c9a98535675961fdfe89e7bfd656720e0140e874c496fd5fdee0dc738a7deab4944286aafa38cfed896863f

data/.yardstick.yml

@@ -27,12 +27,31 @@ rules:
       - Loqate::APIResult#errors?
       - Loqate::APIResult#items
       - Loqate::APIResult#initialize
+      - Loqate::BatchEmailValidation#status
+      - Loqate::BatchEmailValidation#email_address
+      - Loqate::BatchEmailValidation#account
+      - Loqate::BatchEmailValidation#domain
+      - Loqate::BatchEmailValidation#is_disposible
+      - Loqate::BatchEmailValidation#is_system_mailbox
       - Loqate::Configuration#api_key
       - Loqate::Configuration#host
       - Loqate::Configuration#language
       - Loqate::Configuration#initialize
       - Loqate::DetailedAddress#initialize
       - Loqate::DetailedAddress#==
+      - Loqate::EmailGateway#initialize
+      - Loqate::EmailValidation#response_code
+      - Loqate::EmailValidation#response_message
+      - Loqate::EmailValidation#email_address
+      - Loqate::EmailValidation#user_account
+      - Loqate::EmailValidation#domain
+      - Loqate::EmailValidation#is_disposable_or_temporary
+      - Loqate::EmailValidation#is_complainer_or_fraud_risk
+      - Loqate::EmailValidation#duration
+      - Loqate::EmailValidation#valid?
+      - Loqate::EmailValidation#valid_domain?
+      - Loqate::EmailValidation#invalid?
+      - Loqate::EmailValidation#timeout?
       - Loqate::Error#id
       - Loqate::Error#description
       - Loqate::Error#cause
@@ -41,6 +60,7 @@ rules:
       - Loqate::Gateway#config
       - Loqate::Gateway#initialize
       - Loqate::Gateway#address
+      - Loqate::Gateway#email
       - Loqate::Gateway#phone
       - Loqate::PhoneGateway#initialize
       - Loqate::PhoneNumberValidation#phone_number
@@ -81,6 +101,12 @@ rules:
       - Loqate::Client#format_params
       - Loqate::Client#headers
       - Loqate::DetailedAddress#==
+      - Loqate::EmailGateway#error_mapper
+      - Loqate::EmailGateway#client
+      - Loqate::EmailGateway#mapper
+      - Loqate::EmailGateway#build_error_from
+      - Loqate::EmailGateway#build_email_validation_from
+      - Loqate::EmailGateway#build_email_validations_from
       - Loqate::Util.camelize
       - Loqate::Util#camelize
       - Loqate::Util.underscore
@@ -115,6 +141,12 @@ rules:
       - Loqate::Client#headers
       - Loqate::DetailedAddress#initialize
       - Loqate::DetailedAddress#==
+      - Loqate::EmailGateway#error_mapper
+      - Loqate::EmailGateway#client
+      - Loqate::EmailGateway#mapper
+      - Loqate::EmailGateway#build_error_from
+      - Loqate::EmailGateway#build_email_validation_from
+      - Loqate::EmailGateway#build_email_validations_from
       - Loqate::Error#attributes
       - Loqate::Gateway#client
       - Loqate::PhoneGateway#mapper

data/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2018-11-20
+### Added
+- Email API
+
 ## [0.4.0] - 2018-11-14
 ### Changed
 - Updated the gem `HTTP` to version `4.0.0`
@@ -45,6 +49,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Initial core functionality
 - Codebase maintenance tools
 
+[0.4.0]: https://github.com/wilsonsilva/loqate/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/wilsonsilva/loqate/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/wilsonsilva/loqate/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/wilsonsilva/loqate/compare/v0.1.0...v0.2.0

data/README.md

@@ -21,6 +21,9 @@ Client to address verification, postcode lookup, & data quality services from Lo
     - [Retrieving the details of an address](#retrieving-the-details-of-an-address)
   - [Phone API](#phone-api)
     - [Validating a phone number](#validating-a-phone-number)
+  - [Email API](#phone-api)
+    - [Validating an email address](#validating-an-email-address)
+    - [Validating multiple email addresses](#validating-multiple-email-addresses)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -142,6 +145,50 @@ phone_validation.country_prefix    # => 44
 phone_validation.number_type       # => 'Mobile'
 ```
 
+### Email API
+
+The Email API consists of two main API requests:
+[Validate](https://www.loqate.com/resources/support/apis/EmailValidation/Interactive/Validate/2/) request to validate
+a single email adress; and a
+[Batch Validate](https://www.loqate.com/resources/support/apis/EmailValidation/Batch/Validate/1.2/) request to
+validate multiple emails at once.
+
+#### Validating an email address
+```ruby
+email_validation = gateway.email.validate!(email: 'person@gmail.com')
+
+email_validation.response_code               # => 'Valid'
+email_validation.response_message            # => 'Email address was fully validated'
+email_validation.email_address               # => 'person@gmail.com'
+email_validation.user_account                # => 'person'
+email_validation.domain                      # => 'gmail.com'
+email_validation.is_disposable_or_temporary  # => false
+email_validation.is_complainer_or_fraud_risk # => false
+email_validation.duration                    # => 0.007366261
+email_validation.valid?                      # => true
+email_validation.valid_domain?               # => true
+email_validation.invalid?                    # => false
+email_validation.timeout?                    # => false
+```
+
+#### Validating multiple email addresses
+
+```ruby                                                                    
+email_validations = gateway.email.batch_validate!(emails: %w[person@gmail.com])
+email_validation = email_validations.first
+
+email_validation.status            # => 'Valid'
+email_validation.email_address     # => 'person@gmail.com'
+email_validation.account           # => 'person'
+email_validation.domain            # => 'gmail.com'
+email_validation.is_disposible     # => false
+email_validation.is_system_mailbox # => false
+email_validation.valid?            # => true
+email_validation.invalid?          # => false
+email_validation.unknown?          # => false
+email_validation.unverified?       # => false
+```
+   
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies, configure git hooks and create support files.

data/ROADMAP.md

@@ -17,7 +17,7 @@
 - [x] Address Verification
 - [ ] Geocode
 - [ ] Data Cleanse
-- [ ] Email Verification
+- [x] Email Verification
 - [x] Phone Verification
 - [ ] Bank Verification
 

data/lib/loqate/batch_email_validation.rb

@@ -0,0 +1,66 @@
+module Loqate
+  # Result of a batch email address validation.
+  class BatchEmailValidation < Dry::Struct::Value
+    Status = Types::Strict::String.enum('Valid', 'Invalid', 'Unknown', 'Accept_All')
+
+    # Valid - The email address is valid
+    # Invalid - The email address is invalid and shouldn't be accepted
+    # Unknown - Unable to complete the verification process (normally due to SMTP timeout)
+    # Accept_All - The mail server is set to accept all verification requests so full verification isn't possible
+    #
+    # @return ['Valid', 'Invalid', 'Unknown', 'Accept_All']
+    #
+    attribute :status, Status
+
+    # The email address that verification was attempted on.
+    #
+    # @return [String]
+    #
+    attribute :email_address, Types::Strict::String
+
+    # The account portion of the email address provided.
+    #
+    # @return [String
+    #
+    attribute :account, Types::Strict::String
+
+    # The domain portion of the email address provided.
+    #
+    # @return [String]
+    #
+    attribute :domain, Types::Strict::String
+
+    # Whether the email address provided is a disposable mailbox (some companies create temporary mailboxes
+    # which shouldn't be used for marketing communications).
+    #
+    # @return [Boolean]
+    #
+    attribute :is_disposible, Types::Strict::Bool
+
+    # Whether the email address provided is a system mailbox (e.g. sales@, support@, accounts@ etc).
+    #
+    # @return [Boolean]
+    #
+    attribute :is_system_mailbox, Types::Strict::Bool
+
+    # Whether the email was fully validated (including the account portion).
+    def valid?
+      status == 'Valid'
+    end
+
+    # Whether the email is invalid and shouldn't be accepted.
+    def invalid?
+      status == 'Invalid'
+    end
+
+    # Whether the email wasn't verified (normally due to SMTP timeout)
+    def unknown?
+      status == 'Unknown'
+    end
+
+    # Whether the email could be verified
+    def unverified?
+      status == 'Accept_All'
+    end
+  end
+end

data/lib/loqate/email_gateway.rb

@@ -0,0 +1,122 @@
+require 'loqate/client'
+require 'loqate/result'
+require 'loqate/email_validation'
+require 'loqate/batch_email_validation'
+require 'loqate/mappers/error_mapper'
+require 'loqate/mappers/generic_mapper'
+
+module Loqate
+  # Validates the existence of email addresses.
+  #
+  class EmailGateway
+    BATCH_VALIDATE_ENDPOINT = '/EmailValidation/Batch/Validate/v1.20/json3.ws'.freeze
+    VALIDATE_ENDPOINT = '/EmailValidation/Interactive/Validate/v2.00/json3.ws'.freeze
+
+    include Result::Mixin
+
+    # Creates an email gateway.
+    #
+    # @param [Client] client The client responsible for the HTTP interactions
+    #
+    def initialize(client)
+      @client       = client
+      @mapper       = Mappers::GenericMapper.new
+      @error_mapper = Mappers::ErrorMapper.new
+    end
+
+    # Verifies the existence of an email address.
+    #
+    # @param [Hash] options The options to validate an email address.
+    # @option options [String] :email The email address to verify.
+    # @option options [Integer] :timeout The time (in milliseconds) you want to give for the validation attempt to be
+    #   executed within. Value must be between 1 and 15000 (values outside of these ranges will fallback to the
+    #   default of 15000).
+    #
+    # @example
+    #   email_validation = email_gateway.validate(email: 'spam@example.com')
+    #
+    # @return [Result] A result wrapping an email address validation
+    #
+    def validate(options)
+      response = client.get(VALIDATE_ENDPOINT, options)
+
+      response.errors? && build_error_from(response.items.first) || build_email_validation_from(response.items.first)
+    end
+
+    # Verifies the existence of an email address.
+    #
+    # @param [Hash] options The options to validate an email address.
+    # @option options [String] :email The email address to verify.
+    # @option options [Integer] :timeout The time (in milliseconds) you want to give for the validation attempt to be
+    #   executed within. Value must be between 1 and 15000 (values outside of these ranges will fallback to the
+    #   default of 15000).
+    #
+    # @example
+    #   email_validation = email_gateway.validate!(email: 'spam@example.com')
+    #
+    # @raise [Error] If the result is not a success
+    #
+    # @return [EmailValidation> An email address validation
+    #
+    def validate!(options)
+      unwrap_result_or_raise { validate(options) }
+    end
+
+    # Verifies up to 100 emails per batch.
+    #
+    # @param [Hash] options The options to validate an email address.
+    # @option options [Array<String>] :emails The email addresses to verify. Maximum 100 records.
+    #
+    # @example
+    #   result = email_gateway.batch_validate(emails: %w[spam@example.com example@example.com])
+    #   result.value # => [#<Loqate::BatchEmailValidation status="Invalid" ...]
+    #
+    # @return [Result] A result wrapping a list of email address validations
+    #
+    def batch_validate(options)
+      options[:emails] = options[:emails].join(',') if options[:emails]
+      response = client.get(BATCH_VALIDATE_ENDPOINT, options)
+
+      response.errors? && build_error_from(response.items.first) || build_email_validations_from(response.items)
+    end
+
+    # Verifies up to 100 emails per batch.
+    #
+    # @param [Hash] options The options to validate an email address.
+    # @option options [Array<String>] :emails The email addresses to verify. Maximum 100 records.
+    #
+    # @example
+    #   email_validations = email_gateway.batch_validate!(emails: %w[spam@example.com example@example.com])
+    #
+    # @raise [Error] If the result is not a success
+    #
+    # @return [Array<BatchEmailValidation>] A list of email address validations
+    #
+    def batch_validate!(options)
+      unwrap_result_or_raise { batch_validate(options) }
+    end
+
+    private
+
+    # @api private
+    attr_reader :client, :mapper, :error_mapper
+
+    # @api private
+    def build_error_from(item)
+      error = error_mapper.map_one(item)
+      Failure(error)
+    end
+
+    # @api private
+    def build_email_validation_from(item)
+      email_validation = mapper.map_one(item, EmailValidation)
+      Success(email_validation)
+    end
+
+    # @api private
+    def build_email_validations_from(item)
+      email_validation = mapper.map(item, BatchEmailValidation)
+      Success(email_validation)
+    end
+  end
+end

data/lib/loqate/email_validation.rb

@@ -0,0 +1,81 @@
+module Loqate
+  # Result of a email address validation.
+  class EmailValidation < Dry::Struct::Value
+    ResponseCode = Types::Strict::String.enum('Valid', 'Valid_CatchAll', 'Invalid', 'Timeout')
+
+    # Valid - The email address has been fully validated (including the account portion)
+    # Valid_CatchAll - The domain has been validated but the account could not be validated
+    # Invalid - The email address is invalid and shouldn't be accepted
+    # Timeout - The validation could not be completed within the timeout specified (try increasing the timeout value)
+    #
+    # @return ['Valid', 'Valid_CatchAll', 'Invalid', 'Timeout']
+    #
+    attribute :response_code, ResponseCode
+
+    # A textual description of the ResponseCode returned
+    #
+    # @return [String]
+    #
+    attribute :response_message, Types::Strict::String
+
+    # The email address that verification was attempted on.
+    #
+    # @return [String]
+    #
+    attribute :email_address, Types::Strict::String
+
+    # The account portion of the email address provided.
+    #
+    # @return [String
+    #
+    attribute :user_account, Types::Strict::String
+
+    # The domain portion of the email address provided.
+    #
+    # @return [String]
+    #
+    attribute :domain, Types::Strict::String
+
+    # Whether the email address provided is a disposable mailbox (some companies create temporary mailboxes
+    # which shouldn't be used for marketing communications).
+    #
+    # @return [Boolean]
+    #
+    attribute :is_disposable_or_temporary, Types::Strict::Bool
+
+    # True if we recognise the email address against known lists of complainers and/or the email address has been
+    # used to defraud.
+    #
+    # @return [Boolean]
+    #
+    attribute :is_complainer_or_fraud_risk, Types::Strict::Bool
+
+    # The duration (in seconds) that the email validation took (maximum timeout enforced at 15 seconds).
+    # We recommend a high timeout (at least 5 seconds) value as it will minimise the number of "Timeout"
+    # responses returned.
+    #
+    # @return [Float]
+    #
+    attribute :duration, Types::Strict::Float
+
+    # Whether the email was fully validated (including the account portion).
+    def valid?
+      response_code == 'Valid'
+    end
+
+    # Whether the domain has been validated but the account hasn't.
+    def valid_domain?
+      response_code == 'Valid' || response_code == 'Valid_CatchAll'
+    end
+
+    # Whether the email is invalid and shouldn't be accepted.
+    def invalid?
+      response_code == 'Invalid'
+    end
+
+    # Whether the validation could not be completed within the timeout specified.
+    def timeout?
+      response_code == 'Timeout'
+    end
+  end
+end

data/lib/loqate/gateway.rb

@@ -1,4 +1,5 @@
 require 'loqate/address_gateway'
+require 'loqate/email_gateway'
 require 'loqate/phone_gateway'
 
 module Loqate
@@ -40,6 +41,14 @@ module Loqate
       @phone ||= PhoneGateway.new(client)
     end
 
+    # Gateway to the Email verification APIs.
+    #
+    # @return [EmailGateway] An instance of an email gateway.
+    #
+    def email
+      @email ||= EmailGateway.new(client)
+    end
+
     private
 
     # @api private

data/lib/loqate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Loqate
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: loqate
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Wilson Silva
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-14 00:00:00.000000000 Z
+date: 2018-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-struct
@@ -347,9 +347,12 @@ files:
 - lib/loqate/address.rb
 - lib/loqate/address_gateway.rb
 - lib/loqate/api_result.rb
+- lib/loqate/batch_email_validation.rb
 - lib/loqate/client.rb
 - lib/loqate/configuration.rb
 - lib/loqate/detailed_address.rb
+- lib/loqate/email_gateway.rb
+- lib/loqate/email_validation.rb
 - lib/loqate/error.rb
 - lib/loqate/gateway.rb
 - lib/loqate/mappers/error_mapper.rb