truelist-rails

validates :email, deliverable: true

gem "truelist-rails"

class User < ApplicationRecord
  validates :email, presence: true, deliverable: true
end

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

validates :email, deliverable: true

validates :email, deliverable: { allow_risky: false }

validates :email, deliverable: { message: "is not a valid email address" }

validates :email, deliverable: { allow_risky: false, message: "doesn't look right" }

validates :email, presence: true,
                  format: { with: URI::MailTo::EMAIL_REGEXP },
                  deliverable: true

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)

client = Truelist::Client.new
account = client.account

account["email"]                   # => "team@company.com"
account["name"]                    # => "Team Lead"
account["uuid"]                    # => "a3828d19-..."
account["account"]["payment_plan"] # => "pro"

Truelist.configure do |config|
  config.cache_store = Rails.cache
  config.cache_ttl = 1.hour
end

Truelist.configure do |config|
  config.raise_on_error = true
end

# 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

allow(Truelist::Client).to receive(:new).and_return(
  instance_double(Truelist::Client, validate: Truelist::Result.new(email: "user@example.com", state: "ok"))
)