clean-email 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4325a9205cc1e85f87c8791415b7845a0132c7b4a59fc87b5d1b7f62c816a34d
+  data.tar.gz: '048b1b3b60ff7b27f4500791f33961718011493a9282cc29f6a41da521dd0ad9'
+SHA512:
+  metadata.gz: 547dba76b5a2a233a0ed2df32edd349a73ad1fde51335cf69c32db2f71d0432030d0dde6cb7995bc05b59ec53c3469e9f8b941b911e326ba5f06e9e7a916c63a
+  data.tar.gz: 822404c6745e72b017b044d2cb5605c9bb82164c0ddef7d389a79ef24e8d56bc0dce6076b943500ddfffa010e3bb4018049c8bf1853bfa71bc2ae5af9e0e488e

data/README.md

@@ -0,0 +1,345 @@
+# clean-email
+
+[![Gem Version](https://badge.fury.io/rb/clean-email.png)](http://badge.fury.io/rb/clean-email)
+![Gem Downloads (for latest version)](https://img.shields.io/gem/dtv/clean-email) 
+
+Ruby gem for email validation with support for multiple providers ([Reoon](https://reoon.com/email-verifier-api/), [ZeroBounce](https://www.zerobounce.net/), [AbstractAPI](https://www.abstractapi.com/email-validation-api)), with optional smart caching to minimize API usage.
+
+Unlike SMTP-based validators, clean-email uses HTTP APIs backed by continuously updated datasets — making it faster, more reliable across all environments, and capable of detecting **disposable** and **spamtrap** addresses that SMTP handshakes simply cannot identify.
+
+## How it works
+
+Every validation follows this priority order:
+
+1. **Invalid format** — malformed emails are rejected immediately, no cache, no API call
+2. **Domain cache** — if the domain is already marked as `disposable` or `spamtrap`, it is rejected instantly without hitting the API
+3. **Email cache** — if the full email was validated before, the cached result is returned
+4. **Provider API** — only called when no cache is available; the result is stored for future use
+
+The domain-level cache is the key to API savings: once `mailinator.com` is identified as disposable, any future email `@mailinator.com` is rejected without a single API call.
+
+**No database?** The adapter is optional. Without one, every call goes straight to the provider API — no caching at all.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "clean-email"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Setup
+
+### Rails
+
+Run the install generator to create the initializer and the migration:
+
+```bash
+rails generate clean_email:install
+rails db:migrate
+```
+
+This creates:
+- `config/initializers/clean_email.rb` — configuration file
+- `db/migrate/TIMESTAMP_create_clean_email_caches.rb` — tables for email and domain caching
+
+Then configure your chosen provider in the initializer (see [Configuration](#configuration-options) below).
+
+### Non-Rails projects
+
+Require and configure the gem manually:
+
+```ruby
+require "clean_email"
+
+CleanEmail.configure do |config|
+  config.provider      = :reoon
+  config.reoon_api_key = ENV["REOON_API_KEY"]
+  config.adapter       = MyAdapter.new  # optional — see Adapter section
+end
+```
+
+### Without a database
+
+Simply omit the adapter. Every call will hit the provider API directly:
+
+```ruby
+CleanEmail.configure do |config|
+  config.provider      = :reoon
+  config.reoon_api_key = ENV["REOON_API_KEY"]
+end
+```
+
+## Configuration options
+
+| Option | Description | Default |
+|---|---|---|
+| `provider` | Which API to use: `:reoon`, `:zerobounce`, or `:abstractapi` | `:reoon` |
+| `reoon_api_key` | Reoon API key. Required when `provider: :reoon`. | — |
+| `reoon_mode` | `:quick` (faster) or `:power` (more accurate) | `:quick` |
+| `zerobounce_api_key` | ZeroBounce API key. Required when `provider: :zerobounce`. | — |
+| `abstractapi_key` | AbstractAPI key. Required when `provider: :abstractapi`. | — |
+| `adapter` | An instance of `CleanEmail::Adapters::Base`. Optional. | `nil` |
+| `blocked_statuses` | Statuses rejected by the ActiveModel/Devise validator. | `%w[invalid disposable spamtrap]` |
+
+### Provider examples
+
+**Reoon:**
+```ruby
+CleanEmail.configure do |config|
+  config.provider      = :reoon
+  config.reoon_api_key = ENV["REOON_API_KEY"]
+  config.reoon_mode    = :quick  # or :power
+  config.adapter       = CleanEmail::Adapters::ActiveRecord.new
+end
+```
+
+**ZeroBounce:**
+```ruby
+CleanEmail.configure do |config|
+  config.provider            = :zerobounce
+  config.zerobounce_api_key  = ENV["ZEROBOUNCE_API_KEY"]
+  config.adapter             = CleanEmail::Adapters::ActiveRecord.new
+end
+```
+
+**AbstractAPI:**
+```ruby
+CleanEmail.configure do |config|
+  config.provider       = :abstractapi
+  config.abstractapi_key = ENV["ABSTRACTAPI_KEY"]
+  config.adapter        = CleanEmail::Adapters::ActiveRecord.new
+end
+```
+
+## Usage
+
+```ruby
+result = CleanEmail.validate("user@example.com")
+
+result.valid?       # => true / false
+result.invalid?     # => true / false
+result.status       # => "valid", "invalid", "disposable", "spamtrap", "unknown"
+result.disposable?  # => true / false
+result.spamtrap?    # => true / false
+result.cached?      # => true if result came from cache (no API call was made)
+result.to_h         # => { email:, status:, valid:, cached: }
+```
+
+Or instantiate the validator directly to reuse the same instance:
+
+```ruby
+validator = CleanEmail::Validator.new
+
+validator.validate("a@example.com")
+validator.validate("b@example.com")
+```
+
+## Normalized statuses
+
+Regardless of which provider you use, all results are normalized to a common set of statuses:
+
+| Status | Meaning | `valid?` |
+|---|---|---|
+| `valid` | Email exists and accepts messages | `true` |
+| `invalid` | Invalid email or non-existent domain | `false` |
+| `disposable` | Temporary / throwaway email service | `false` |
+| `spamtrap` | Anti-spam trap address | `false` |
+| `unknown` | Provider could not determine | `false` |
+
+### Provider status mapping
+
+**Reoon** → normalized:
+
+| Reoon status | Normalized |
+|---|---|
+| `valid` | `valid` |
+| `invalid` | `invalid` |
+| `disposable` | `disposable` |
+| `spamtrap` | `spamtrap` |
+| `unknown` | `unknown` |
+
+**ZeroBounce** → normalized:
+
+| ZeroBounce status | Sub-status | Normalized |
+|---|---|---|
+| `valid` | — | `valid` |
+| `invalid` | — | `invalid` |
+| `catch-all` | — | `unknown` |
+| `unknown` | — | `unknown` |
+| `spamtrap` | — | `spamtrap` |
+| `abuse` | — | `invalid` |
+| `do_not_mail` | `disposable` | `disposable` |
+| `do_not_mail` | other | `invalid` |
+
+**AbstractAPI** → normalized:
+
+| `is_disposable_email` | `deliverability` | Normalized |
+|---|---|---|
+| `true` | any | `disposable` |
+| `false` | `DELIVERABLE` | `valid` |
+| `false` | `UNDELIVERABLE` | `invalid` |
+| `false` | `RISKY` / `UNKNOWN` | `unknown` |
+
+## Adapter
+
+The gem is storage-agnostic. You can implement `CleanEmail::Adapters::Base` with any backend, or use the built-in adapters.
+
+### Built-in: ActiveRecord (Rails)
+
+Generated automatically by `rails generate clean_email:install`. Creates two tables:
+
+- `clean_email_email_caches` — caches full email results
+- `clean_email_domain_caches` — caches disposable/spamtrap domains
+
+```ruby
+config.adapter = CleanEmail::Adapters::ActiveRecord.new
+```
+
+### Built-in: Memory (tests and prototyping)
+
+Data lives only for the duration of the process:
+
+```ruby
+config.adapter = CleanEmail::Adapters::Memory.new
+```
+
+### Custom adapter interface
+
+Implement four methods:
+
+```ruby
+class MyAdapter < CleanEmail::Adapters::Base
+  # Persist a validated email result
+  def store_email(email, result)   = raise NotImplementedError
+  # Return a CleanEmail::Result or nil
+  def find_email(email)            = raise NotImplementedError
+
+  # Persist a domain marked as "disposable" or "spamtrap"
+  def store_domain(domain, status) = raise NotImplementedError
+  # Return "disposable", "spamtrap", or nil
+  def find_domain(domain)          = raise NotImplementedError
+end
+```
+
+### Redis example
+
+```ruby
+class RedisAdapter < CleanEmail::Adapters::Base
+  TTL_EMAIL  = 7  * 24 * 60 * 60  # 7 days
+  TTL_DOMAIN = 30 * 24 * 60 * 60  # 30 days
+
+  def initialize(redis = Redis.current)
+    @redis = redis
+  end
+
+  def store_email(email, result)
+    @redis.setex("email_valid:#{email}", TTL_EMAIL, result.status)
+  end
+
+  def find_email(email)
+    status = @redis.get("email_valid:#{email}")
+    return nil unless status
+    CleanEmail::Result.new(email: email, status: status)
+  end
+
+  def store_domain(domain, status)
+    @redis.setex("domain_valid:#{domain}", TTL_DOMAIN, status)
+  end
+
+  def find_domain(domain)
+    @redis.get("domain_valid:#{domain}")
+  end
+end
+```
+
+## Devise / ActiveModel integration
+
+The gem ships with an opt-in `ActiveModel` validator that can be used in any model — including Devise's `User`.
+
+### Setup
+
+Add `validates :email, clean_email: true` to your model:
+
+```ruby
+class User < ApplicationRecord
+  devise :database_authenticatable, :registerable, ...
+
+  validates :email, clean_email: true
+end
+```
+
+The validator calls the configured provider API (with caching if an adapter is configured) and rejects any status listed in `blocked_statuses`.
+
+The API is only called when necessary: on new records, or when the email attribute has actually changed. Saving other fields (e.g. name, avatar) does not trigger a new API call.
+
+### Configuring which statuses are blocked
+
+Set a global default in the initializer:
+
+```ruby
+CleanEmail.configure do |config|
+  config.provider      = :zerobounce
+  config.zerobounce_api_key = ENV["ZEROBOUNCE_API_KEY"]
+
+  # Reject disposable and invalid emails; allow "unknown" through
+  config.blocked_statuses = %w[invalid disposable spamtrap]
+end
+```
+
+Or override per-model:
+
+```ruby
+# Only block outright invalid emails
+validates :email, clean_email: { blocked_statuses: %w[invalid] }
+```
+
+### Custom error message
+
+```ruby
+validates :email, clean_email: { message: "is not accepted" }
+```
+
+### API errors
+
+If the provider API is unreachable, the validator rejects the email and logs a warning via `Rails.logger`. To change this behaviour, rescue `CleanEmail::ApiError` in a `before_validation` callback.
+
+## Error handling
+
+| Exception | When raised |
+|---|---|
+| `CleanEmail::ConfigurationError` | Required API key not set, or unknown provider |
+| `CleanEmail::ApiError` | HTTP request failed or provider returned an invalid response |
+
+```ruby
+begin
+  result = CleanEmail.validate(email)
+rescue CleanEmail::ApiError => e
+  # API failed — decide whether to reject or accept provisionally
+  Rails.logger.error("Email validation error: #{e.message}")
+end
+```
+
+## Reoon API modes
+
+Only applicable when `provider: :reoon`:
+
+- **`:quick`** — Fast validation based on syntax, DNS, and known lists. Recommended for real-time validation.
+- **`:power`** — Full validation including SMTP verification. More accurate but slower. Best for batch processing.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/clean-email.rb

@@ -0,0 +1 @@
+require_relative "clean_email"

data/lib/clean_email/abstract_api_client.rb

@@ -0,0 +1,59 @@
+require "faraday"
+require "json"
+
+module CleanEmail
+  # Thin wrapper around the Abstract Email Validation API.
+  # https://docs.abstractapi.com/email-validation
+  class AbstractApiClient
+    BASE_URL = "https://emailreputation.abstractapi.com/v1/"
+
+    def initialize(api_key:)
+      @api_key = api_key
+    end
+
+    # @param email [String]
+    # @return [CleanEmail::Result]
+    # @raise [CleanEmail::ApiError]
+    def validate(email)
+      response = connection.get do |req|
+        req.params["api_key"] = @api_key
+        req.params["email"]   = email
+      end
+
+      handle_response(email, response)
+    rescue Faraday::Error => e
+      raise ApiError, "AbstractAPI request failed: #{e.message}"
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL) do |f|
+        f.response :raise_error
+        f.options.timeout      = 10
+        f.options.open_timeout = 5
+      end
+    end
+
+    def handle_response(email, response)
+      body = JSON.parse(response.body)
+      status = extract_status(body)
+      Result.new(email: email, status: status, raw: body)
+    rescue JSON::ParserError => e
+      raise ApiError, "Invalid JSON from AbstractAPI: #{e.message}"
+    rescue Faraday::Error => e
+      raise ApiError, "AbstractAPI request failed: #{e.message}"
+    end
+
+    def extract_status(body)
+      # Disposable check takes priority regardless of deliverability
+      return "disposable" if body.dig("is_disposable_email", "value") == true
+
+      case body["deliverability"].to_s.upcase
+      when "DELIVERABLE"   then "valid"
+      when "UNDELIVERABLE" then "invalid"
+      else                      "unknown"
+      end
+    end
+  end
+end

data/lib/clean_email/active_model_validator.rb

@@ -0,0 +1,33 @@
+# ActiveModel/Devise integration for CleanEmail.
+#
+# Opt-in by adding to your model (e.g. User):
+#
+#   validates :email, clean_email: true
+#
+# This calls the Reoon API (with caching if an adapter is configured) and
+# rejects any status listed in CleanEmail.configuration.blocked_statuses.
+#
+# You can override blocked statuses per-validator:
+#
+#   validates :email, clean_email: { blocked_statuses: %w[invalid] }
+#
+# Or customise the error message:
+#
+#   validates :email, clean_email: { message: "is not accepted" }
+#
+class CleanEmailValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return if record.persisted? && !record.will_save_change_to_attribute?(attribute)
+
+    result = CleanEmail.validate(value.to_s)
+
+    blocked = options.fetch(:blocked_statuses, CleanEmail.configuration.blocked_statuses)
+
+    if blocked.include?(result.status)
+      record.errors.add(attribute, options[:message] || :invalid)
+    end
+  rescue CleanEmail::ApiError => e
+    record.errors.add(attribute, options[:message] || :invalid)
+    Rails.logger.warn("[CleanEmail] API error during validation: #{e.message}") if defined?(Rails)
+  end
+end

data/lib/clean_email/adapters/active_record.rb

@@ -0,0 +1,60 @@
+require_relative "base"
+
+module CleanEmail
+  module Adapters
+    # ActiveRecord adapter. Requires the tables created by the install generator:
+    #
+    #   rails generate clean_email:install
+    #   rails db:migrate
+    #
+    # Then configure:
+    #
+    #   CleanEmail.configure do |c|
+    #     c.adapter = CleanEmail::Adapters::ActiveRecord.new
+    #   end
+    class ActiveRecord < Base
+      EMAIL_MODEL  = "CleanEmail::EmailCache"
+      DOMAIN_MODEL = "CleanEmail::DomainCache"
+
+      def store_email(email, result)
+        email_model.upsert(
+          { email: email, status: result.status },
+          unique_by: :email
+        )
+      end
+
+      def find_email(email)
+        row = email_model.find_by(email: email)
+        return nil unless row
+        Result.new(email: row.email, status: row.status)
+      end
+
+      def store_domain(domain, status)
+        domain_model.upsert(
+          { domain: domain, status: status },
+          unique_by: :domain
+        )
+      end
+
+      def find_domain(domain)
+        domain_model.find_by(domain: domain)&.status
+      end
+
+      private
+
+      def email_model
+        Object.const_get(EMAIL_MODEL)
+      rescue NameError
+        raise ConfigurationError,
+          "#{EMAIL_MODEL} model not found. Did you run `rails generate clean_email:install` and `rails db:migrate`?"
+      end
+
+      def domain_model
+        Object.const_get(DOMAIN_MODEL)
+      rescue NameError
+        raise ConfigurationError,
+          "#{DOMAIN_MODEL} model not found. Did you run `rails generate clean_email:install` and `rails db:migrate`?"
+      end
+    end
+  end
+end

data/lib/clean_email/adapters/base.rb

@@ -0,0 +1,43 @@
+module CleanEmail
+  module Adapters
+    # Base interface for storage adapters.
+    #
+    # Implement this in your application to plug in any storage backend
+    # (ActiveRecord, Redis, SQLite, etc.).
+    #
+    # All methods must be implemented by subclasses.
+    class Base
+      # Persist a validated email result.
+      #
+      # @param email [String] the full email address
+      # @param result [CleanEmail::Result]
+      def store_email(email, result)
+        raise NotImplementedError, "#{self.class}#store_email not implemented"
+      end
+
+      # Retrieve a cached result for an email.
+      #
+      # @param email [String]
+      # @return [CleanEmail::Result, nil] nil if not cached
+      def find_email(email)
+        raise NotImplementedError, "#{self.class}#find_email not implemented"
+      end
+
+      # Persist a domain marked as disposable or spamtrap.
+      #
+      # @param domain [String] e.g. "mailinator.com"
+      # @param status [String] "disposable" or "spamtrap"
+      def store_domain(domain, status)
+        raise NotImplementedError, "#{self.class}#store_domain not implemented"
+      end
+
+      # Retrieve a cached domain status.
+      #
+      # @param domain [String]
+      # @return [String, nil] "disposable", "spamtrap", or nil if not cached
+      def find_domain(domain)
+        raise NotImplementedError, "#{self.class}#find_domain not implemented"
+      end
+    end
+  end
+end

data/lib/clean_email/adapters/memory.rb

@@ -0,0 +1,30 @@
+require_relative "base"
+
+module CleanEmail
+  module Adapters
+    # In-memory adapter. Useful for tests and quick prototyping.
+    # Data is lost when the process exits.
+    class Memory < Base
+      def initialize
+        @emails  = {}
+        @domains = {}
+      end
+
+      def store_email(email, result)
+        @emails[email.downcase] = result
+      end
+
+      def find_email(email)
+        @emails[email.downcase]
+      end
+
+      def store_domain(domain, status)
+        @domains[domain.downcase] = status
+      end
+
+      def find_domain(domain)
+        @domains[domain.downcase]
+      end
+    end
+  end
+end

data/lib/clean_email/configuration.rb

@@ -0,0 +1,53 @@
+module CleanEmail
+  class Configuration
+    PROVIDERS = %i[reoon zerobounce abstractapi].freeze
+
+    # Which provider to use: :reoon, :zerobounce, or :abstractapi
+    attr_accessor :provider
+
+    # Reoon-specific options
+    attr_accessor :reoon_api_key
+    attr_accessor :reoon_mode
+
+    # ZeroBounce-specific options
+    attr_accessor :zerobounce_api_key
+
+    # AbstractAPI-specific options
+    attr_accessor :abstractapi_key
+
+    # An object implementing CleanEmail::Adapters::Base
+    attr_accessor :adapter
+
+    # Statuses that cause the ActiveModel validator to reject the email.
+    # Used by `validates :email, clean_email: true` in Devise (or any model).
+    # Possible values: "invalid", "disposable", "spamtrap", "unknown"
+    attr_accessor :blocked_statuses
+
+    def initialize
+      @provider           = :reoon
+      @reoon_mode         = :quick
+      @adapter            = nil
+      @reoon_api_key      = nil
+      @zerobounce_api_key = nil
+      @abstractapi_key    = nil
+      @blocked_statuses   = %w[invalid disposable spamtrap]
+    end
+
+    def validate!
+      case provider.to_sym
+      when :reoon
+        raise ConfigurationError, "reoon_api_key is required" if reoon_api_key.nil? || reoon_api_key.empty?
+      when :zerobounce
+        raise ConfigurationError, "zerobounce_api_key is required" if zerobounce_api_key.nil? || zerobounce_api_key.empty?
+      when :abstractapi
+        raise ConfigurationError, "abstractapi_key is required" if abstractapi_key.nil? || abstractapi_key.empty?
+      else
+        raise ConfigurationError, "Unknown provider: #{provider}. Use one of: #{PROVIDERS.join(', ')}"
+      end
+    end
+
+    def adapter?
+      !adapter.nil?
+    end
+  end
+end

data/lib/clean_email/models/domain_cache.rb

@@ -0,0 +1,8 @@
+module CleanEmail
+  class DomainCache < ::ActiveRecord::Base
+    self.table_name = "clean_email_domain_caches"
+
+    validates :domain, presence: true, uniqueness: true
+    validates :status, presence: true
+  end
+end

data/lib/clean_email/models/email_cache.rb

@@ -0,0 +1,8 @@
+module CleanEmail
+  class EmailCache < ::ActiveRecord::Base
+    self.table_name = "clean_email_email_caches"
+
+    validates :email,  presence: true, uniqueness: true
+    validates :status, presence: true
+  end
+end

data/lib/clean_email/reoon_client.rb

@@ -0,0 +1,60 @@
+require "faraday"
+require "json"
+
+module CleanEmail
+  # Thin wrapper around the Reoon Email Verifier API.
+  # https://reoon.com/email-verifier-api/
+  class ReoonClient
+    BASE_URL = "https://emailverifier.reoon.com/api/v1/verify"
+
+    VALID_STATUSES = %w[valid invalid disposable spamtrap unknown].freeze
+
+    def initialize(api_key:, mode: :quick)
+      @api_key = api_key
+      @mode    = mode.to_s  # "quick" or "power"
+    end
+
+    # @param email [String]
+    # @return [CleanEmail::Result]
+    # @raise [CleanEmail::ApiError]
+    def validate(email)
+      response = connection.get do |req|
+        req.params["email"]   = email
+        req.params["key"]     = @api_key
+        req.params["mode"]    = @mode
+      end
+
+      handle_response(email, response)
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL) do |f|
+        f.response :raise_error
+        f.options.timeout      = 10
+        f.options.open_timeout = 5
+      end
+    end
+
+    def handle_response(email, response)
+      body = JSON.parse(response.body)
+
+      # Reoon wraps results; extract the status field
+      status = extract_status(body)
+
+      Result.new(email: email, status: status, raw: body)
+    rescue JSON::ParserError => e
+      raise ApiError, "Invalid JSON from Reoon: #{e.message}"
+    rescue Faraday::Error => e
+      raise ApiError, "Reoon API request failed: #{e.message}"
+    end
+
+    def extract_status(body)
+      # Reoon v1 response shape:
+      # { "status": "valid"|"invalid"|"disposable"|"spamtrap"|..., ... }
+      raw_status = body["status"].to_s.downcase
+      VALID_STATUSES.include?(raw_status) ? raw_status : "unknown"
+    end
+  end
+end

data/lib/clean_email/result.rb

@@ -0,0 +1,53 @@
+module CleanEmail
+  # Wraps the outcome of an email validation check.
+  class Result
+    # Reoon statuses that make an email unusable
+    BAD_STATUSES = %w[disposable spamtrap].freeze
+
+    attr_reader :email, :status, :raw
+
+    # @param email  [String] the validated email
+    # @param status [String] Reoon status: "valid", "invalid", "disposable",
+    #                        "spamtrap", "unknown", etc.
+    # @param raw    [Hash]   the full Reoon API response (may be nil for
+    #                        domain-level cache hits)
+    def initialize(email:, status:, raw: nil)
+      @email  = email
+      @status = status
+      @raw    = raw
+    end
+
+    def valid?
+      status == "valid"
+    end
+
+    def invalid?
+      !valid?
+    end
+
+    def disposable?
+      status == "disposable"
+    end
+
+    def spamtrap?
+      status == "spamtrap"
+    end
+
+    # True when the domain alone is enough to reject (no API call needed next time)
+    def bad_domain?
+      BAD_STATUSES.include?(status)
+    end
+
+    def cached?
+      raw.nil?
+    end
+
+    def to_h
+      { email: email, status: status, valid: valid?, cached: cached? }
+    end
+
+    def inspect
+      "#<CleanEmail::Result email=#{email.inspect} status=#{status.inspect} valid=#{valid?}>"
+    end
+  end
+end

data/lib/clean_email/validator.rb

@@ -0,0 +1,88 @@
+module CleanEmail
+  class Validator
+    BASIC_FORMAT = /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/
+
+    def initialize(config = CleanEmail.configuration)
+      @config = config
+    end
+
+    # Validate an email address.
+    #
+    # Resolution order (when an adapter is configured):
+    #   1. Reject malformed emails immediately (no cache, no API call)
+    #   2. If domain is cached as disposable/spamtrap → reject instantly
+    #   3. If full email is cached → return cached result
+    #   4. Call the configured provider API → cache result → return
+    #
+    # Without an adapter every call goes straight to the provider API.
+    #
+    # @param email [String]
+    # @return [CleanEmail::Result]
+    def validate(email)
+      @config.validate!
+
+      email = email.to_s.strip.downcase
+
+      return malformed_result(email) unless looks_like_email?(email)
+
+      return client.validate(email) unless adapter?
+
+      domain = extract_domain(email)
+
+      # 1. Domain-level cache (cheapest check)
+      if (domain_status = adapter.find_domain(domain))
+        return Result.new(email: email, status: domain_status)
+      end
+
+      # 2. Full email cache
+      if (cached = adapter.find_email(email))
+        return cached
+      end
+
+      # 3. API call
+      result = client.validate(email)
+
+      # Cache at domain level for disposable/spamtrap — any future email
+      # from this domain gets rejected without hitting the API
+      adapter.store_domain(domain, result.status) if result.bad_domain?
+      adapter.store_email(email, result)
+
+      result
+    end
+
+    private
+
+    def client
+      @client ||= case @config.provider.to_sym
+                  when :reoon
+                    ReoonClient.new(api_key: @config.reoon_api_key, mode: @config.reoon_mode)
+                  when :zerobounce
+                    ZeroBounceClient.new(api_key: @config.zerobounce_api_key)
+                  when :abstractapi
+                    AbstractApiClient.new(api_key: @config.abstractapi_key)
+                  else
+                    raise ConfigurationError, "Unknown provider: #{@config.provider}"
+                  end
+    end
+
+    def adapter
+      @config.adapter
+    end
+
+    def adapter?
+      @config.adapter?
+    end
+
+    def looks_like_email?(email)
+      BASIC_FORMAT.match?(email)
+    end
+
+    def extract_domain(email)
+      email.split("@", 2).last
+    end
+
+    def malformed_result(email)
+      Result.new(email: email, status: "invalid")
+    end
+  end
+end

data/lib/clean_email/version.rb

@@ -0,0 +1,3 @@
+module CleanEmail
+  VERSION = "0.1.0"
+end

data/lib/clean_email/zerobounce_client.rb

@@ -0,0 +1,71 @@
+require "faraday"
+require "json"
+
+module CleanEmail
+  # Thin wrapper around the ZeroBounce Email Validation API.
+  # https://www.zerobounce.net/docs/email-validation-api-quickstart/
+  class ZeroBounceClient
+    BASE_URL = "https://api.zerobounce.net/v2/validate"
+
+    # ZeroBounce status → normalized CleanEmail status
+    STATUS_MAP = {
+      "valid"       => "valid",
+      "invalid"     => "invalid",
+      "catch-all"   => "unknown",
+      "unknown"     => "unknown",
+      "spamtrap"    => "spamtrap",
+      "abuse"       => "invalid",
+      "do_not_mail" => "invalid"
+    }.freeze
+
+    def initialize(api_key:)
+      @api_key = api_key
+    end
+
+    # @param email [String]
+    # @return [CleanEmail::Result]
+    # @raise [CleanEmail::ApiError]
+    def validate(email)
+      response = connection.get do |req|
+        req.params["api_key"]    = @api_key
+        req.params["email"]      = email
+        req.params["ip_address"] = ""
+      end
+
+      handle_response(email, response)
+    rescue Faraday::Error => e
+      raise ApiError, "ZeroBounce API request failed: #{e.message}"
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL) do |f|
+        f.response :raise_error
+        f.options.timeout      = 10
+        f.options.open_timeout = 5
+      end
+    end
+
+    def handle_response(email, response)
+      body = JSON.parse(response.body)
+      status = extract_status(body)
+      Result.new(email: email, status: status, raw: body)
+    rescue JSON::ParserError => e
+      raise ApiError, "Invalid JSON from ZeroBounce: #{e.message}"
+    rescue Faraday::Error => e
+      raise ApiError, "ZeroBounce API request failed: #{e.message}"
+    end
+
+    def extract_status(body)
+      raw_status = body["status"].to_s.downcase
+
+      # do_not_mail with sub_status "disposable" is a disposable address
+      if raw_status == "do_not_mail" && body["sub_status"].to_s.downcase == "disposable"
+        return "disposable"
+      end
+
+      STATUS_MAP.fetch(raw_status, "unknown")
+    end
+  end
+end

data/lib/clean_email.rb

@@ -0,0 +1,45 @@
+require_relative "clean_email/version"
+require_relative "clean_email/configuration"
+require_relative "clean_email/result"
+require_relative "clean_email/reoon_client"
+require_relative "clean_email/zerobounce_client"
+require_relative "clean_email/abstract_api_client"
+require_relative "clean_email/validator"
+require_relative "clean_email/adapters/base"
+require_relative "clean_email/adapters/memory"
+
+if defined?(ActiveRecord)
+  require_relative "clean_email/adapters/active_record"
+  require_relative "clean_email/models/email_cache"
+  require_relative "clean_email/models/domain_cache"
+end
+
+# ActiveModel validator (enables `validates :email, clean_email: true` in
+# Devise models or any ActiveModel-backed class).
+require_relative "clean_email/active_model_validator" if defined?(ActiveModel)
+
+module CleanEmail
+  class Error            < StandardError; end
+  class ConfigurationError < Error; end
+  class ApiError           < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Convenience method: CleanEmail.validate("user@example.com")
+    # Uses the globally configured validator.
+    def validate(email)
+      Validator.new.validate(email)
+    end
+  end
+end

data/lib/generators/clean_email/install/install_generator.rb

@@ -0,0 +1,32 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module CleanEmail
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a CleanEmail initializer and ActiveRecord migration."
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/clean_email.rb"
+      end
+
+      def copy_migration
+        migration_template(
+          "migration.rb.tt",
+          "db/migrate/create_clean_email_caches.rb",
+          migration_version: migration_version
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: clean-email
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TapGoods
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails-omakase
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Validates emails via the Reoon API while minimizing API usage through
+  storage-agnostic caching. Disposable and spamtrap domains are cached
+  at the domain level so subsequent emails from the same domain are
+  rejected instantly without an API call.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/clean-email.rb
+- lib/clean_email.rb
+- lib/clean_email/abstract_api_client.rb
+- lib/clean_email/active_model_validator.rb
+- lib/clean_email/adapters/active_record.rb
+- lib/clean_email/adapters/base.rb
+- lib/clean_email/adapters/memory.rb
+- lib/clean_email/configuration.rb
+- lib/clean_email/models/domain_cache.rb
+- lib/clean_email/models/email_cache.rb
+- lib/clean_email/reoon_client.rb
+- lib/clean_email/result.rb
+- lib/clean_email/validator.rb
+- lib/clean_email/version.rb
+- lib/clean_email/zerobounce_client.rb
+- lib/generators/clean_email/install/install_generator.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Email validation using Reoon with smart local caching
+test_files: []