Trueform Ruby SDK

The official Ruby client for the Trueform email validation API.

Ruby SDK documentation | API reference

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 CONTRIBUTING.md before opening a pull request. Report vulnerabilities through the process in SECURITY.md.

License

MIT. See LICENSE.