Truemail

Whitelist and Blacklist checks act as a 'zero validation level'. If an email or domain matches these lists, the validation result is determined immediately, and no further validation steps (like MX or SMTP) are performed.

Sequence of domain list checks:

1. Whitelist check
2. Whitelist validation check (whitelist_validation setting)
3. Blacklist check

If an email is in the whitelisted_emails list, the validation returns true immediately. If it is in the blacklisted_emails list, it returns false immediately.

require 'truemail'

Truemail.configure do |config|
  config.verifier_email = 'verifier@example.com'
  config.whitelisted_emails = %w[user@somedomain1.com user@somedomain2.com]
  config.blacklisted_emails = %w[user@somedomain3.com user@somedomain4.com]
  config.whitelisted_domains = %w[white-domain.com somedomain.com]
  config.blacklisted_domains = %w[black-domain.com somedomain.com]
  config.validation_type_for = { 'somedomain.com' => :mx }
end

# This will return true immediately due to whitelist
Truemail.validate('email@white-domain.com')

For high-fidelity integration tests, you can use dns_mock and smtp_mock to simulate real network services. This approach requires configuring Truemail to point to the local mock servers for DNS and SMTP ports.

# Gemfile

group :test do
  gem 'dns_mock', require: false
  gem 'smtp_mock', require: false
end

# spec/spec_helper.rb

require 'dns_mock/test_framework/rspec'
require 'smtp_mock/test_framework/rspec'

RSpec.configure do |config|
  config.include DnsMock::TestFramework::RSpec::Helper
  config.include SmtpMock::TestFramework::RSpec::Helper
end

# spec/integration_spec.rb

RSpec.describe 'integration tests' do
  let(:target_email) { random_email }
  let(:dns_mock_records) { dns_mock_records_by_email(target_email, dimension: 2) }

before do
    dns_mock_server.assign_mocks(dns_mock_records)
    smtp_mock_server(**smtp_mock_server_options)

Truemail.configuration.tap do |config|
      config.dns = %W[127.0.0.1:#{dns_mock_server.port}]
      config.smtp_port = smtp_mock_server.port
    end
  end

context 'when checks real email' do
    let(:smtp_mock_server_options) { {} }

it { expect(Truemail.validate(target_email).result).to be_valid }
  end

context 'when checks fake email' do
    let(:smtp_mock_server_options) { { not_registered_emails: [target_email] } }

it { expect(Truemail.validate(target_email).result).not_to be_valid }
  end
end

To use Truemail's global configuration features, you must first initialize it using Truemail.configure. This allows you to set parameters like the verifier email, timeouts, and validation types that will be used across your application.

Note that verifier_email is a required parameter and must be an existing email address used to perform the verification.

require 'truemail'

Truemail.configure do |config|
  # Required parameter. Must be an existing email on behalf of which verification will be performed
  config.verifier_email = 'verifier@example.com'

  # Optional parameter. Must be an existing domain on behalf of which verification will be performed.
  # By default verifier domain based on verifier email
  config.verifier_domain = 'somedomain.com'

  # Optional parameter. You can override default regex pattern
  config.email_pattern = /regex_pattern/

  # Optional parameter. You can override default regex pattern
  config.smtp_error_body_pattern = /regex_pattern/

  # Optional parameter. Connection timeout in seconds. It is equal to 2 by default.
  config.connection_timeout = 1

  # Optional parameter. A SMTP server response timeout in seconds. It is equal to 2 by default.
  config.response_timeout = 1

  # Optional parameter. Total of connection attempts. It is equal to 2 by default.
  config.connection_attempts = 3

  # Optional parameter. You can predefine default validation type for Truemail.validate('email@email.com') call without with-parameter
  # Available validation types: :regex, :mx, :mx_blacklist, :smtp
  config.default_validation_type = :mx

  # Optional parameter. You can predefine which type of validation will be used for domains.
  config.validation_type_for = { 'somedomain.com' => :regex, 'otherdomain.com' => :mx }

  # Optional parameter. Validation of email which contains whitelisted emails always will return true.
  config.whitelisted_emails = %w[user@somedomain1.com user@somedomain2.com]

  # Optional parameter. Validation of email which contains blacklisted emails always will return false.
  config.blacklisted_emails = %w[user@somedomain3.com user@somedomain4.com]

  # Optional parameter. Validation of email which contains whitelisted domain always will return true.
  config.whitelisted_domains = %w[somedomain1.com somedomain2.com]

  # Optional parameter. Validation of email which contains blacklisted domain always will return false.
  config.blacklisted_domains = %w[somedomain3.com somedomain4.com]

  # Optional parameter. With this option Truemail will validate email which contains whitelisted domain only.
  config.whitelist_validation = true

  # Optional parameter. Filter out unwanted mx servers via predefined list of ip addresses.
  config.blacklisted_mx_ip_addresses = %w[1.1.1.1 2.2.2.2]

  # Optional parameter. Custom DNS gateway(s). Format: 'IP' or 'IP:PORT'.
  config.dns = %w[10.0.0.1 10.0.0.2:54]

  # Optional parameter. Use not RFC MX lookup flow.
  config.not_rfc_mx_lookup_flow = true

  # Optional parameter. SMTP port number. Default is 25.
  config.smtp_port = 2525

  # Optional parameter. Ends smtp validation session after first attempt on the first mx server in any fail cases.
  config.smtp_fail_fast = true

  # Optional parameter. Parse bodies of SMTP errors.
  config.smtp_safe_check = true

  # Optional parameter. Enable tracking events.
  config.logger = {
    tracking_event: :all,
    stdout: true,
    log_absolute_path: '/home/app/log/truemail.log'
  }
end