truelist 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4cc95465750e1a4ac521ef820c07005f72cfacb9f02a4970aefd2b64aace82ca
+  data.tar.gz: 8679e804ef330c865a60ffaf0a02ffa6a437cb8854f36b8731dd666ec2218381
+SHA512:
+  metadata.gz: b3fd1de9cde0aa2f490b46e583ef5dfde91359afe658d8374441a44f7edc500a6212ae7acfa4b731829090cc158c62ca5a851032ccf1ebcf1c80ca779fbddd25
+  data.tar.gz: a667a27d4f64fb1715aedcc97fc993d9feafca53c22ad0b88efd6082acb06f4b7c6795f524d0011db4a5870d665f4640d44037c8e8712c0cc926ce6fe11ee778

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Truelist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,288 @@
+# truelist
+
+[![Free tier](https://img.shields.io/badge/free_plan-100_validations-4A7C59?style=flat-square)](https://truelist.io/pricing)
+Ruby SDK for [Truelist.io](https://truelist.io) email validation.
+
+[![Gem Version](https://badge.fury.io/rb/truelist.svg)](https://badge.fury.io/rb/truelist)
+[![CI](https://github.com/Truelist-io-Email-Validation/truelist-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/Truelist-io-Email-Validation/truelist-ruby/actions/workflows/ci.yml)
+
+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 →](https://app.truelist.io/signup?utm_source=github&utm_medium=readme&utm_campaign=free-plan&utm_content=truelist-ruby)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "truelist"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install truelist
+```
+
+## Quick Start
+
+```ruby
+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
+
+```ruby
+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
+
+```ruby
+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:
+
+```ruby
+result = Truelist.validate("user@example.com")
+```
+
+## Configuration
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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).
+
+```ruby
+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](https://github.com/Truelist-io-Email-Validation/truelist-rails) which provides ActiveModel validators on top of this gem:
+
+```ruby
+# Gemfile
+gem "truelist-rails"
+
+# app/models/user.rb
+validates :email, deliverable: true
+```
+
+## Testing
+
+Stub the API in your tests with WebMock:
+
+```ruby
+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:
+
+```ruby
+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
+
+```bash
+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](https://app.truelist.io/signup?utm_source=github&utm_medium=readme&utm_campaign=free-plan&utm_content=truelist-ruby) 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](LICENSE).

data/lib/truelist/account_info.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Truelist
+  class AccountInfo
+    attr_reader :email, :name, :uuid, :time_zone, :is_admin_role, :payment_plan
+
+    def initialize(email:, name:, uuid:, time_zone:, is_admin_role:, payment_plan:)
+      @email = email
+      @name = name
+      @uuid = uuid
+      @time_zone = time_zone
+      @is_admin_role = is_admin_role
+      @payment_plan = payment_plan
+      freeze
+    end
+
+    def admin?
+      @is_admin_role
+    end
+  end
+end

data/lib/truelist/client.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Truelist
+  class Client
+    def initialize(api_key: nil, **options)
+      @api_key = api_key
+      @base_url = options[:base_url]
+      @timeout = options[:timeout]
+      @max_retries = options[:max_retries]
+      @raise_on_error = options[:raise_on_error]
+    end
+
+    def validate(email)
+      uri = URI("#{base_url}/api/v1/verify_inline?email=#{URI.encode_www_form_component(email)}")
+
+      response = request_with_retries(:post, uri)
+      parse_validation_response(email, response)
+    rescue Truelist::AuthenticationError
+      raise
+    rescue StandardError => e
+      handle_error(email, e)
+    end
+
+    def account
+      uri = URI("#{base_url}/me")
+
+      response = request_with_retries(:get, uri)
+      parse_account_response(response)
+    rescue Truelist::AuthenticationError
+      raise
+    rescue StandardError
+      raise if raise_on_error?
+
+      nil
+    end
+
+    private
+
+    def config = Truelist.configuration
+    def api_key = @api_key || config.api_key!
+    def base_url = @base_url || config.base_url
+    def timeout = @timeout || config.timeout
+    def max_retries = @max_retries || config.max_retries
+
+    def raise_on_error?
+      return @raise_on_error unless @raise_on_error.nil?
+
+      config.raise_on_error
+    end
+
+    def request_with_retries(method, uri, auth_key: nil)
+      retries = 0
+      key = auth_key || api_key
+
+      loop do
+        response = perform_request(method, uri, auth_key: key)
+        check_authentication!(response)
+
+        return response if response.code.to_i < 429 || retries >= max_retries
+
+        if retryable_status?(response.code.to_i)
+          retries += 1
+          sleep(backoff_delay(retries))
+          next
+        end
+
+        return response
+      end
+    end
+
+    def check_authentication!(response)
+      return unless response.code.to_i == 401
+
+      raise Truelist::AuthenticationError, 'Invalid API key. Check your Truelist API key configuration.'
+    end
+
+    def retryable_status?(status)
+      status == 429 || status >= 500
+    end
+
+    def backoff_delay(retry_count)
+      (2**retry_count) * 0.1
+    end
+
+    def perform_request(method, uri, auth_key: nil)
+      http = build_http(uri)
+
+      request = build_request(method, uri, auth_key: auth_key || api_key)
+      http.request(request)
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http
+    end
+
+    def build_request(method, uri, auth_key: nil)
+      request = case method
+                when :get then Net::HTTP::Get.new(uri)
+                when :post then Net::HTTP::Post.new(uri)
+                end
+
+      request['Authorization'] = "Bearer #{auth_key || api_key}"
+      request['Content-Type'] = 'application/json'
+      request['Accept'] = 'application/json'
+      request['User-Agent'] = "truelist-ruby/#{Truelist::VERSION}"
+
+      request
+    end
+
+    def parse_validation_response(email, response)
+      status = response.code.to_i
+
+      case status
+      when 200
+        parse_success(email, response.body)
+      when 429
+        handle_error(email, Truelist::RateLimitError.new('Rate limit exceeded'))
+      else
+        handle_error(email, Truelist::ApiError.new("API returned #{status}: #{response.body}",
+                                                   status: status, body: response.body))
+      end
+    end
+
+    def parse_success(email_input, body)
+      data = JSON.parse(body)
+      email_data = data['emails']&.first || {}
+
+      Result.new(
+        email: email_data['address'] || email_input,
+        state: email_data['email_state'] || 'unknown',
+        sub_state: email_data['email_sub_state'],
+        suggestion: email_data['did_you_mean'],
+        domain: email_data['domain'],
+        canonical: email_data['canonical'],
+        mx_record: email_data['mx_record'],
+        first_name: email_data['first_name'],
+        last_name: email_data['last_name'],
+        verified_at: email_data['verified_at']
+      )
+    rescue JSON::ParserError => e
+      handle_error(email_input, e)
+    end
+
+    def parse_account_response(response)
+      status = response.code.to_i
+
+      case status
+      when 200
+        data = JSON.parse(response.body)
+        AccountInfo.new(
+          email: data['email'],
+          name: data['name'],
+          uuid: data['uuid'],
+          time_zone: data['time_zone'],
+          is_admin_role: data['is_admin_role'],
+          payment_plan: data.dig('account', 'payment_plan')
+        )
+      when 429
+        raise Truelist::RateLimitError, 'Rate limit exceeded'
+      else
+        raise Truelist::ApiError.new("API returned #{status}: #{response.body}",
+                                     status: status, body: response.body)
+      end
+    end
+
+    def handle_error(email, error)
+      raise error if raise_on_error?
+
+      Result.new(email: email, state: 'unknown', error: true)
+    end
+  end
+end

data/lib/truelist/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Truelist
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout, :max_retries, :raise_on_error
+
+    def initialize
+      @api_key = ENV.fetch('TRUELIST_API_KEY', nil)
+      @base_url = 'https://api.truelist.io'
+      @timeout = 10
+      @max_retries = 2
+      @raise_on_error = false
+    end
+
+    def api_key!
+      api_key || raise(Truelist::AuthenticationError,
+                       'Truelist API key is not configured. Set TRUELIST_API_KEY or use Truelist.configure.')
+    end
+  end
+end

data/lib/truelist/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Truelist
+  class Error < StandardError; end
+
+  class AuthenticationError < Error; end
+
+  class RateLimitError < Error; end
+
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+end

data/lib/truelist/result.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Truelist
+  class Result
+    attr_reader :email, :state, :sub_state, :suggestion, :domain, :canonical, :mx_record,
+                :first_name, :last_name, :verified_at, :error
+
+    def initialize(email:, state:, sub_state: nil, suggestion: nil, domain: nil, canonical: nil, mx_record: nil,
+                   first_name: nil, last_name: nil, verified_at: nil, error: false)
+      @email = email
+      @state = state.to_s
+      @sub_state = sub_state&.to_s
+      @suggestion = suggestion
+      @domain = domain
+      @canonical = canonical
+      @mx_record = mx_record
+      @first_name = first_name
+      @last_name = last_name
+      @verified_at = verified_at
+      @error = error
+      freeze
+    end
+
+    def valid?(allow_risky: false)
+      return %w[ok accept_all].include?(state) if allow_risky
+
+      state == 'ok'
+    end
+
+    def deliverable?(allow_risky: true)
+      valid?(allow_risky: allow_risky)
+    end
+
+    def invalid?
+      state == 'email_invalid'
+    end
+
+    def accept_all?
+      state == 'accept_all'
+    end
+
+    def unknown?
+      state == 'unknown'
+    end
+
+    def disposable?
+      sub_state == 'is_disposable'
+    end
+
+    def role?
+      sub_state == 'is_role'
+    end
+
+    def error?
+      @error
+    end
+  end
+end

data/lib/truelist/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Truelist
+  VERSION = '0.2.0'
+end

data/lib/truelist.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'truelist/version'
+require_relative 'truelist/errors'
+require_relative 'truelist/configuration'
+require_relative 'truelist/result'
+require_relative 'truelist/account_info'
+require_relative 'truelist/client'
+
+module Truelist
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def validate(email)
+      Client.new.validate(email)
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: truelist
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Truelist
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-08 00:00:00.000000000 Z
+dependencies: []
+description: Pure Ruby client for the Truelist.io email validation API. Verify email
+  deliverability with zero dependencies. Works anywhere Ruby runs — no Rails required.
+email:
+- support@truelist.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/truelist.rb
+- lib/truelist/account_info.rb
+- lib/truelist/client.rb
+- lib/truelist/configuration.rb
+- lib/truelist/errors.rb
+- lib/truelist/result.rb
+- lib/truelist/version.rb
+homepage: https://github.com/Truelist-io-Email-Validation/truelist-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Truelist-io-Email-Validation/truelist-ruby
+  source_code_uri: https://github.com/Truelist-io-Email-Validation/truelist-ruby
+  changelog_uri: https://github.com/Truelist-io-Email-Validation/truelist-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for Truelist.io email validation
+test_files: []