truelist-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d9bf2a865512806998948b308b302c98a30edab2919c23ad3bd6c3b22d93191
+  data.tar.gz: 382931bfc3208ad233801783b070d92c998d529f6d7bdc7863b8292422471b4d
+SHA512:
+  metadata.gz: '085a171c764b96fc40dbfb188f4391fca2e4be34195cbf98f9ef6f297a9642e955f035dd8a6b533e04f9d9bc165a5ee9698ae6817448b9c7ea5c3a295021d006'
+  data.tar.gz: e178b7747e44a6efcc31565f42fda5d0d2e23dd4922dcb4d0978dd6602190d978492b62ece467dfe63c8704c95390793777361e7566cdad16ff445b4f6249270

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Truelist
+
+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.

data/README.md

@@ -0,0 +1,261 @@
+# truelist-rails
+
+[![Free tier](https://img.shields.io/badge/free_plan-100_validations-4A7C59?style=flat-square)](https://truelist.io/pricing)
+Email validation for Rails, powered by [Truelist.io](https://truelist.io).
+
+[![Gem Version](https://badge.fury.io/rb/truelist-rails.svg)](https://badge.fury.io/rb/truelist-rails)
+[![CI](https://github.com/Truelist-io-Email-Validation/truelist-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/Truelist-io-Email-Validation/truelist-rails/actions/workflows/ci.yml)
+
+Validate email deliverability in your Rails models with a single line:
+
+```ruby
+validates :email, deliverable: true
+```
+
+Truelist checks whether an email address actually exists and can receive mail, catching typos, disposable addresses, and invalid mailboxes before they hit your database.
+
+> **Start free** — 100 validations + 10 enhanced credits, no credit card required.
+> [Get your API key →](https://app.truelist.io/signup?utm_source=github&utm_medium=readme&utm_campaign=free-plan&utm_content=truelist-rails)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "truelist-rails"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Configure your API key
+
+Set the `TRUELIST_API_KEY` environment variable, or run the install generator:
+
+```bash
+rails generate truelist:install
+```
+
+This creates `config/initializers/truelist.rb` where you can configure the gem.
+
+### 2. Add the validator
+
+```ruby
+class User < ApplicationRecord
+  validates :email, presence: true, deliverable: true
+end
+```
+
+That's it. Invalid emails will now fail validation with a clear error message.
+
+## Configuration
+
+```ruby
+Truelist.configure do |config|
+  # Your Truelist API key (required).
+  # Defaults to ENV["TRUELIST_API_KEY"].
+  config.api_key = ENV["TRUELIST_API_KEY"]
+
+  # API base URL. Change only for testing or proxying.
+  config.base_url = "https://api.truelist.io"
+
+  # Request timeout in seconds.
+  config.timeout = 10
+
+  # When true, raises Truelist::Error on API failures.
+  # When false (default), returns an "unknown" result on errors,
+  # allowing the validation to pass gracefully.
+  config.raise_on_error = false
+
+  # Whether "accept_all" emails (domains that accept all addresses) pass validation.
+  config.allow_risky = true
+
+  # Optional cache store for validation results.
+  # Accepts any Rails-compatible cache store.
+  config.cache_store = Rails.cache
+
+  # How long to cache validation results (in seconds).
+  config.cache_ttl = 1.hour
+end
+```
+
+## Validator Options
+
+### Basic usage
+
+```ruby
+validates :email, deliverable: true
+```
+
+### Reject accept_all emails
+
+```ruby
+validates :email, deliverable: { allow_risky: false }
+```
+
+### Custom error message
+
+```ruby
+validates :email, deliverable: { message: "is not a valid email address" }
+```
+
+### Combine options
+
+```ruby
+validates :email, deliverable: { allow_risky: false, message: "doesn't look right" }
+```
+
+### Use with other validators
+
+```ruby
+validates :email, presence: true,
+                  format: { with: URI::MailTo::EMAIL_REGEXP },
+                  deliverable: true
+```
+
+The `deliverable` validator skips blank values, so pair it with `presence: true` if the field is required.
+
+## Working with Results Directly
+
+Use the client to validate emails outside of model validations:
+
+```ruby
+result = Truelist.validate("user@example.com")
+
+result.state       # => "ok", "email_invalid", "accept_all", or "unknown"
+result.sub_state   # => "email_ok", "is_disposable", "is_role", etc.
+result.valid?      # => true when state is "ok" (or "accept_all" with allow_risky)
+result.invalid?    # => true when state is "email_invalid"
+result.accept_all? # => true when state is "accept_all"
+result.unknown?    # => true when state is "unknown"
+
+result.email        # => the validated email address
+result.suggestion   # => suggested correction, if available
+result.domain       # => email domain
+result.canonical    # => local part of the email
+result.mx_record    # => MX record for the domain
+result.first_name   # => first name, if available
+result.last_name    # => last name, if available
+result.verified_at  # => timestamp of verification
+result.disposable?  # => whether it's a disposable/temporary address (sub_state)
+result.role?        # => whether it's a role address (sub_state)
+```
+
+### Account Info
+
+```ruby
+client = Truelist::Client.new
+account = client.account
+
+account["email"]                   # => "team@company.com"
+account["name"]                    # => "Team Lead"
+account["uuid"]                    # => "a3828d19-..."
+account["account"]["payment_plan"] # => "pro"
+```
+
+### Sub-states
+
+| Sub-state | Meaning |
+|-----------|---------|
+| `email_ok` | Email is valid and deliverable |
+| `is_disposable` | Disposable/temporary email |
+| `is_role` | Role-based address (info@, admin@) |
+| `failed_smtp_check` | SMTP check failed |
+| `failed_mx_check` | Domain has no mail server |
+| `failed_spam_trap` | Known spam trap address |
+| `failed_no_mailbox` | Mailbox does not exist |
+| `failed_greylisted` | Server temporarily rejected (greylisting) |
+| `failed_syntax_check` | Email format is invalid |
+| `unknown_error` | Could not determine status |
+
+## Caching
+
+Enable caching to avoid redundant API calls for recently validated emails:
+
+```ruby
+Truelist.configure do |config|
+  config.cache_store = Rails.cache
+  config.cache_ttl = 1.hour
+end
+```
+
+The cache key is based on the lowercase, stripped email address. Any Rails-compatible cache store works (Redis, Memcached, file store, etc.).
+
+## Error Handling
+
+By default, API errors (timeouts, rate limits, server errors) return an `unknown` result, allowing validation to pass. This prevents your forms from breaking when the API is unreachable.
+
+To raise exceptions instead:
+
+```ruby
+Truelist.configure do |config|
+  config.raise_on_error = true
+end
+```
+
+Exception classes:
+
+- `Truelist::Error` -- base error class
+- `Truelist::ApiError` -- unexpected API responses
+- `Truelist::AuthenticationError` -- invalid API key (401)
+- `Truelist::RateLimitError` -- rate limit exceeded (429)
+
+## Testing
+
+Stub the API in your tests to avoid real HTTP calls. With WebMock:
+
+```ruby
+# spec/support/truelist.rb
+RSpec.configure do |config|
+  config.before do
+    stub_request(:post, "https://api.truelist.io/api/v1/verify_inline")
+      .with(query: hash_including(email: /.+/))
+      .to_return(
+        status: 200,
+        body: {
+          emails: [{
+            address: "user@example.com",
+            email_state: "ok",
+            email_sub_state: "email_ok"
+          }]
+        }.to_json,
+        headers: { "Content-Type" => "application/json" }
+      )
+  end
+end
+```
+
+Or stub at the client level:
+
+```ruby
+allow(Truelist::Client).to receive(:new).and_return(
+  instance_double(Truelist::Client, validate: Truelist::Result.new(email: "user@example.com", state: "ok"))
+)
+```
+
+## Requirements
+
+- Ruby >= 3.0
+- Rails >= 7.0 (ActiveModel / ActiveSupport)
+
+## Development
+
+```bash
+git clone https://github.com/Truelist-io-Email-Validation/truelist-rails.git
+cd truelist-rails
+bundle install
+bundle exec rspec
+```
+
+
+## Getting Started
+
+Sign up for a [free Truelist account](https://app.truelist.io/signup?utm_source=github&utm_medium=readme&utm_campaign=free-plan&utm_content=truelist-rails) to get your API key. The free plan includes 100 validations and 10 enhanced credits — no credit card required.
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/generators/truelist/install_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Truelist
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a Truelist initializer in config/initializers'
+
+      def create_initializer
+        template 'initializer.rb', 'config/initializers/truelist.rb'
+      end
+
+      def show_instructions
+        say ''
+        say 'Truelist initializer created at config/initializers/truelist.rb', :green
+        say ''
+        say 'Next steps:'
+        say '  1. Set your API key via TRUELIST_API_KEY environment variable'
+        say '     or uncomment the api_key line in the initializer'
+        say '  2. Add `validates :email, deliverable: true` to your models'
+        say ''
+      end
+    end
+  end
+end

data/lib/generators/truelist/templates/initializer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+Truelist.configure do |config|
+  # Your Truelist API key. Defaults to ENV["TRUELIST_API_KEY"].
+  # config.api_key = ENV["TRUELIST_API_KEY"]
+
+  # API base URL (change only for testing/proxying).
+  # config.base_url = "https://api.truelist.io"
+
+  # Request timeout in seconds.
+  # config.timeout = 10
+
+  # When true, raises Truelist::Error on API failures.
+  # When false (default), returns an "unknown" result on errors.
+  # config.raise_on_error = false
+
+  # Whether "accept_all" emails pass validation.
+  # config.allow_risky = true
+
+  # Optional cache store for validation results.
+  # Uses any Rails-compatible cache store (e.g., Rails.cache).
+  # config.cache_store = Rails.cache
+
+  # How long to cache validation results.
+  # config.cache_ttl = 1.hour
+end

data/lib/truelist/client.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Truelist
+  class Client
+    def initialize(config: Truelist.configuration)
+      @config = config
+    end
+
+    def validate(email)
+      cached = read_cache(email)
+      return cached if cached
+
+      result = perform_request(email)
+      write_cache(email, result) unless result.unknown?
+      result
+    end
+
+    def account
+      uri = URI("#{@config.base_url}/me")
+      http = build_http(uri)
+
+      request = Net::HTTP::Get.new(uri)
+      request['Authorization'] = "Bearer #{@config.api_key!}"
+      request['Accept'] = 'application/json'
+
+      response = http.request(request)
+      handle_status!(response)
+      JSON.parse(response.body)
+    rescue Truelist::AuthenticationError
+      raise
+    rescue StandardError => e
+      raise e if @config.raise_on_error
+
+      nil
+    end
+
+    private
+
+    def perform_request(email)
+      uri = URI("#{@config.base_url}/api/v1/verify_inline")
+      uri.query = URI.encode_www_form(email: email)
+      http = build_http(uri)
+
+      request = Net::HTTP::Post.new(uri)
+      request['Authorization'] = "Bearer #{@config.api_key!}"
+      request['Accept'] = 'application/json'
+
+      response = http.request(request)
+      handle_response(email, response)
+    rescue Truelist::AuthenticationError
+      raise
+    rescue StandardError => e
+      handle_error(email, e)
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = @config.timeout
+      http.read_timeout = @config.timeout
+      http
+    end
+
+    def handle_status!(response)
+      case response.code.to_i
+      when 200 then nil
+      when 401
+        raise Truelist::AuthenticationError, 'Invalid API key. Check your Truelist API key configuration.'
+      else
+        raise Truelist::ApiError, "API returned #{response.code}: #{response.body}"
+      end
+    end
+
+    def handle_response(email, response)
+      case response.code.to_i
+      when 200
+        parse_success(email, response.body)
+      when 401
+        raise Truelist::AuthenticationError, 'Invalid API key. Check your Truelist API key configuration.'
+      when 429
+        handle_error(email, Truelist::RateLimitError.new('Rate limit exceeded'))
+      else
+        handle_error(email, Truelist::ApiError.new("API returned #{response.code}: #{response.body}"))
+      end
+    end
+
+    def parse_success(email, body)
+      d = JSON.parse(body).dig('emails', 0) || {}
+      Result.new(
+        email: d['address'] || email, state: d['email_state'] || 'unknown',
+        sub_state: d['email_sub_state'], suggestion: d['did_you_mean'],
+        domain: d['domain'], canonical: d['canonical'], mx_record: d['mx_record'],
+        first_name: d['first_name'], last_name: d['last_name'], verified_at: d['verified_at']
+      )
+    rescue JSON::ParserError => e
+      handle_error(email, e)
+    end
+
+    def handle_error(email, error)
+      raise error if @config.raise_on_error
+
+      Result.new(email: email, state: 'unknown', error: true)
+    end
+
+    def cache_key(email)
+      "truelist:validation:#{email.downcase.strip}"
+    end
+
+    def read_cache(email)
+      return nil unless @config.cache_store
+
+      @config.cache_store.read(cache_key(email))
+    end
+
+    def write_cache(email, result)
+      return unless @config.cache_store
+
+      @config.cache_store.write(cache_key(email), result, expires_in: @config.cache_ttl)
+    end
+  end
+end

data/lib/truelist/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Truelist
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout, :raise_on_error,
+                  :allow_risky, :cache_store, :cache_ttl
+
+    def initialize
+      @api_key = ENV.fetch('TRUELIST_API_KEY', nil)
+      @base_url = 'https://api.truelist.io'
+      @timeout = 10
+      @raise_on_error = false
+      @allow_risky = true
+      @cache_store = nil
+      @cache_ttl = 3600 # 1 hour in seconds
+    end
+
+    def api_key!
+      api_key || raise(Truelist::AuthenticationError,
+                       'Truelist API key is not configured. Set TRUELIST_API_KEY or use Truelist.configure.')
+    end
+  end
+end

data/lib/truelist/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Truelist
+  class Railtie < Rails::Railtie
+    initializer 'truelist.configure' do
+      Truelist.configure do |config|
+        config.api_key ||= ENV.fetch('TRUELIST_API_KEY', nil)
+      end
+    end
+  end
+end

data/lib/truelist/result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Truelist
+  class Result
+    attr_reader :email, :state, :sub_state, :suggestion, :domain, :canonical,
+                :mx_record, :first_name, :last_name, :verified_at, :error
+
+    def initialize(email:, state:, sub_state: nil, suggestion: nil, domain: nil, canonical: nil,
+                   mx_record: nil, first_name: nil, last_name: nil, verified_at: nil, error: false)
+      @email = email
+      @state = state.to_s
+      @sub_state = sub_state&.to_s
+      @suggestion = suggestion
+      @domain = domain
+      @canonical = canonical
+      @mx_record = mx_record
+      @first_name = first_name
+      @last_name = last_name
+      @verified_at = verified_at
+      @error = error
+    end
+
+    def valid?
+      state == 'ok' || (state == 'accept_all' && Truelist.configuration.allow_risky)
+    end
+
+    def invalid?
+      state == 'email_invalid'
+    end
+
+    def accept_all?
+      state == 'accept_all'
+    end
+
+    def unknown?
+      state == 'unknown'
+    end
+
+    def disposable?
+      sub_state == 'is_disposable'
+    end
+
+    def role?
+      sub_state == 'is_role'
+    end
+
+    def error?
+      @error
+    end
+  end
+end

data/lib/truelist/validators/deliverable_validator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class DeliverableValidator < ActiveModel::EachValidator
+  def validate_each(record, attribute, value)
+    return if value.blank?
+
+    result = Truelist::Client.new.validate(value)
+
+    allow_risky = if options.key?(:allow_risky)
+                    options[:allow_risky]
+                  else
+                    Truelist.configuration.allow_risky
+                  end
+
+    # Fail open for transient errors (timeouts, 500s) so forms still work when API is down
+    return if result.error?
+
+    deliverable = result.state == 'ok' || (result.state == 'accept_all' && allow_risky) || result.unknown?
+
+    return if deliverable
+
+    message = options[:message] || :invalid_email
+    record.errors.add(attribute, message)
+  end
+end

data/lib/truelist/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Truelist
+  VERSION = '0.1.0'
+end

data/lib/truelist.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'truelist/version'
+require_relative 'truelist/configuration'
+require_relative 'truelist/result'
+require_relative 'truelist/client'
+
+module Truelist
+  class Error < StandardError; end
+  class ApiError < Error; end
+  class AuthenticationError < Error; end
+  class RateLimitError < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def validate(email)
+      Client.new.validate(email)
+    end
+  end
+end
+
+require_relative 'truelist/railtie' if defined?(Rails::Railtie)
+require_relative 'truelist/validators/deliverable_validator'

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: truelist-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Truelist
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Rails integration for the Truelist.io email validation API. Validate
+  email deliverability with a simple ActiveModel validator.
+email:
+- support@truelist.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/generators/truelist/install_generator.rb
+- lib/generators/truelist/templates/initializer.rb
+- lib/truelist.rb
+- lib/truelist/client.rb
+- lib/truelist/configuration.rb
+- lib/truelist/railtie.rb
+- lib/truelist/result.rb
+- lib/truelist/validators/deliverable_validator.rb
+- lib/truelist/version.rb
+homepage: https://github.com/Truelist-io-Email-Validation/truelist-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Truelist-io-Email-Validation/truelist-rails
+  source_code_uri: https://github.com/Truelist-io-Email-Validation/truelist-rails
+  changelog_uri: https://github.com/Truelist-io-Email-Validation/truelist-rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+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.4.10
+signing_key: 
+specification_version: 4
+summary: Email validation for Rails, powered by Truelist.io
+test_files: []