Trueform Ruby SDK

The official Ruby client for the Trueform email validation API. Validate email format, disposable and freemail providers, common domain typos, and mail routing without an API key.

Documentation | API reference | RubyGems | Changelog | Issues

Features

• Immutable result objects with idiomatic predicate methods
• Zero runtime dependencies
• Built-in retries for connection failures, timeouts, rate limits, and server errors
• Client-level and per-request configuration

Install

Add the gem to your bundle:

gem "trueform"

Then run bundle install. You can also install it directly with gem install trueform.

The SDK supports Ruby 3.1 and newer. It has no runtime dependencies and does not require an API key.

Quickstart

require "trueform"

trueform = Trueform::Client.new
validation = trueform.validations.create(email: "user@example.com")

puts "Email looks good" if validation.deliverable?

Handle validation results

Validation results are immutable Ruby objects with predicate methods:

if validation.did_you_mean
  puts "Did you mean #{validation.did_you_mean}?"
end

puts "Ask for a permanent email address" if validation.disposable?

Available values and predicates:

• email
• valid_format?
• freemail?
• disposable?
• mx_records?
• did_you_mean
• deliverable?
• to_h

deliverable? is a domain-level verdict. It does not prove that a specific mailbox exists.

Configure the client

Timeout values and retry delays use seconds:

trueform = Trueform::Client.new(
  timeout: 5,
  max_retries: 2
)

Override options for one request:

validation = trueform.validations.create(
  email: "user@example.com",
  timeout: 2,
  max_retries: 0
)

The client retries connection failures, timeouts, rate limits, and server errors. A Retry-After response header controls the delay when present.

Use base_url: to point the client at a different Trueform-compatible endpoint.

Errors

begin
  validation = trueform.validations.create(email: "user@example.com")
rescue Trueform::RateLimitError => error
  warn "Retry after #{error.retry_after} seconds"
rescue Trueform::InvalidRequestError => error
  warn error.message
end

Exported errors:

• Trueform::Error
• Trueform::APIError
• Trueform::InvalidRequestError
• Trueform::RateLimitError
• Trueform::ConnectionError
• Trueform::TimeoutError

Errors expose code, status, request_id, and retry_after when available.

Development

bundle install
bundle exec rake

Read the contributing guide before opening a pull request. Report vulnerabilities through the process in the security policy.

Trueform SDKs

Platform	Registry	Source
Node.js	trueform-node on npm	GitHub
PHP	trueform/trueform on Packagist	GitHub
Ruby	trueform on RubyGems	GitHub
Python	trueform-cloud on PyPI	GitHub

License

MIT. See the license.