Ruby SDK

Official Ruby SDK for the Truelist email validation API. Zero runtime dependencies.

Installation

gem "truelist"

bundle install

Requires Ruby 3.0+.

Quick start

require "truelist"

client = Truelist::Client.new(api_key: "your-api-key")

result = client.validate("user@example.com")
result.state      # => "ok"
result.valid?      # => true
result.domain      # => "example.com"
result.suggestion  # => nil or corrected email

Configuration

Truelist.configure do |config|
  config.api_key = ENV["TRUELIST_API_KEY"]
  config.timeout = 10
  config.max_retries = 2
  config.raise_on_error = false
end

When raise_on_error is false (default), transient errors return a result with error?: true and state: "unknown". Auth errors always raise.

Result predicates

Error handling

begin
  result = client.validate("user@example.com")
rescue Truelist::AuthenticationError
  puts "Bad API key"
rescue Truelist::RateLimitError => e
  puts "Rate limited"
rescue Truelist::ApiError => e
  puts "API error: #{e.message}"
end

Account info

account = client.account
account.email        # => "you@company.com"
account.payment_plan # => "pro"

Rails integration

gem "truelist-rails"

bundle install
rails generate truelist:install

Quick start

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

Configuration (config/initializers/truelist.rb)

Truelist.configure do |config|
  config.api_key = ENV["TRUELIST_API_KEY"]
  config.timeout = 10
  config.raise_on_error = false
  config.allow_risky = true
  config.cache_store = Rails.cache
  config.cache_ttl = 1.hour
end

Validator options

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

Skips blank values — pair with presence: true.

Caching

Any Rails-compatible cache store works. Cache key is the lowercase, stripped email.

config.cache_store = Rails.cache
config.cache_ttl = 1.hour

Requirements

• Ruby 3.0+
• Rails 7.0+

Package links