truelist

Ruby SDK for Truelist.io email validation.

Verify email deliverability with a pure Ruby client. Zero runtime dependencies. Works anywhere Ruby runs -- no Rails required.

Start free — 100 validations + 10 enhanced credits, no credit card required. Get your API key →

Installation

Add to your Gemfile:

gem "truelist"

Then run:

bundle install

Or install directly:

gem install truelist

Quick Start

require "truelist"

# Set your API key (or use TRUELIST_API_KEY env var)
Truelist.configure do |config|
  config.api_key = "your-api-key"
end

# Validate an email
result = Truelist.validate("user@example.com")
result.valid?  # => true
result.state   # => "ok"

Client Usage

Validate an email

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

result = client.validate("user@example.com")
result.state       # => "ok"
result.sub_state   # => "email_ok"
result.valid?      # => true
result.domain      # => "example.com"
result.verified_at # => "2026-02-21T10:00:00.000Z"

Account info

account = client.account
account.email        # => "you@company.com"
account.name         # => "Team Lead"
account.payment_plan # => "pro"
account.admin?       # => true

The account method respects raise_on_error. When disabled (default), transient errors (429, 5xx, timeouts) return nil instead of raising. Authentication errors (401) always raise regardless of this setting.

Shortcut methods

Read TRUELIST_API_KEY from your environment automatically:

result = Truelist.validate("user@example.com")

Configuration

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

  # Max retry attempts on 429/5xx errors.
  config.max_retries = 2

  # When true, raises Truelist::Error on API failures.
  # When false (default), returns an "unknown" result on transient errors,
  # allowing your code to handle failures gracefully.
  config.raise_on_error = false
end

You can also pass configuration per-client:

client = Truelist::Client.new(
  api_key: "different-key",
  base_url: "https://custom.api.com",
  timeout: 30,
  max_retries: 5
)

Error Handling

By default, transient errors (timeouts, rate limits, server errors) return a Result with error?: true and state: "unknown". This prevents your application from breaking when the API is unreachable.

Authentication errors (401) always raise, regardless of the raise_on_error setting.

To raise exceptions on all errors:

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

Exception classes:

• Truelist::Error -- base error class
• Truelist::AuthenticationError -- invalid API key (401)
• Truelist::RateLimitError -- rate limit exceeded (429)
• Truelist::ApiError -- unexpected API responses (includes status and body attributes)

Retries

The client automatically retries on 429 (rate limit) and 5xx (server error) responses with exponential backoff. Configure with max_retries (default: 2).

Truelist.configure do |config|
  config.max_retries = 3  # retry up to 3 times
end

Set to 0 to disable retries.

Result Object

The Truelist::Result is a frozen data object with the following attributes:

Attribute	Type	Description
email	String	The email that was validated
state	String	"ok", "email_invalid", "accept_all", or "unknown"
sub_state	String	Detailed sub-state (see below)
suggestion	String/nil	Suggested correction, if available
domain	String/nil	Domain of the email address
canonical	String/nil	Canonical part of the email
mx_record	String/nil	MX record for the domain
first_name	String/nil	First name associated with the email
last_name	String/nil	Last name associated with the email
verified_at	String/nil	Timestamp of verification
error	Boolean	Whether an API error occurred

Predicates

Method	Returns true when
valid?	State is "ok"
valid?(allow_risky: true)	State is "ok" or "accept_all"
deliverable?	State is "ok" or "accept_all" (alias for valid?(allow_risky: true))
deliverable?(allow_risky: false)	State is "ok" only
invalid?	State is "email_invalid"
accept_all?	State is "accept_all"
unknown?	State is "unknown"
disposable?	Sub-state is "is_disposable"
role?	Sub-state is "is_role"
error?	An API error occurred

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
unknown_error	Could not determine status

Account Info Object

The Truelist::AccountInfo is a frozen data object:

Attribute	Type	Description
email	String	Account email
name	String	Account holder name
uuid	String	Account UUID
time_zone	String	Account time zone
is_admin_role	Boolean	Whether user is admin
payment_plan	String	Current payment plan

Predicates

Method	Returns true when
admin?	User has admin role

For Rails Users

If you're using Rails, check out truelist-rails which provides ActiveModel validators on top of this gem:

# Gemfile
gem "truelist-rails"

# app/models/user.rb
validates :email, deliverable: true

Testing

Stub the API in your tests with WebMock:

require "webmock/rspec"

RSpec.configure do |config|
  config.before do
    stub_request(:post, %r{https://api\.truelist\.io/api/v1/verify_inline})
      .to_return(
        status: 200,
        body: {
          emails: [{
            address: "user@example.com",
            domain: "example.com",
            canonical: "user",
            mx_record: nil,
            first_name: nil,
            last_name: nil,
            email_state: "ok",
            email_sub_state: "email_ok",
            verified_at: "2026-02-21T10:00:00.000Z",
            did_you_mean: nil
          }]
        }.to_json,
        headers: { "Content-Type" => "application/json" }
      )
  end
end

Or stub at the client level:

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
• No runtime dependencies

Development

git clone https://github.com/Truelist-io-Email-Validation/truelist-ruby.git
cd truelist-ruby
bundle install
bundle exec rspec
bundle exec rubocop

Getting Started

Sign up for a free Truelist account 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.