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.