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

• 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

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.

require "trueform"

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

puts "Email looks good" if validation.deliverable?

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.

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.

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.

bundle install
bundle exec rake

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

MIT. See the license.