truemail

Configurable framework agnostic plain Ruby email validator. Verify email via Regex, DNS, SMTP and even more. Be sure that email address valid and exists.

Actual and maintainable documentation :books: for developers is living here.

Table of Contents

• Synopsis
• Features
• Requirements
• Installation
• Usage
  • Configuration features
    • Setting global configuration
      • Read global configuration
      • Update global configuration
      • Reset global configuration
    • Using custom independent configuration
  • Validation features
    • Whitelist/Blacklist check
      • Whitelist case
      • Whitelist validation case
      • Blacklist case
      • Duplication case
    • Regex validation
      • With default regex pattern
      • With custom regex pattern
    • DNS (MX) validation
      • RFC MX lookup flow
      • Not RFC MX lookup flow
    • MX blacklist validation
    • SMTP validation
      • SMTP fail fast enabled
      • SMTP safe check disabled
      • SMTP safe check enabled
  • Host audit features
    • IP audit
    • DNS audit
    • PTR audit
    • Example of using
  • Event logger
    • Using custom logger
    • Available tracking events
  • JSON serializers
    • Auditor JSON serializer
    • Validator JSON serializer
  • Truemail helpers
    • .valid?
    • #as_json
  • Test environment
• Truemail family
• Contributing
• License
• Code of Conduct
• Credits
• Versioning
• Changelog

Synopsis

Email validation is a tricky thing. There are a number of different ways to validate an email address and all mechanisms must conform with the best practices and provide proper validation. The Truemail gem helps you validate emails via regex pattern, presence of DNS records, and real existence of email account on a current email server.

Syntax Checking: Checks the email addresses via regex pattern.

Mail Server Existence Check: Checks the availability of the email address domain using DNS records.

Mail Existence Check: Checks if the email address really exists and can receive email via SMTP connections and email-sending emulation techniques.

Also Truemail gem allows performing an audit of the host in which runs.

Features

• Configurable validator, validate only what you need
• Supporting of internationalized emails (EAI)
• Whitelist/blacklist validation layers
• Ability to configure different MX/SMTP validation flows
• Ability to configure DEA validation flow
• Simple SMTP debugger
• Event logger
• Host auditor tools (helps to detect common host problems interfering to proper email verification)
• JSON serializers
• Ability to use the library as independent stateless microservice (Truemail Server)

Requirements

Ruby MRI 2.5.0+

Installation

Add this line to your application's Gemfile:

gem 'truemail'

And then execute:

bundle

Or install it yourself as:

gem install truemail

Usage

Configuration features

You can use global gem configuration or custom independent configuration. Available configuration options:

• verifier email
• verifier domain
• email pattern
• SMTP error body pattern
• connection timeout
• response timeout
• connection attempts
• default validation type
• validation type for domains
• whitelisted emails
• blacklisted emails
• whitelisted domains
• blacklisted domains
• whitelist validation
• blacklisted mx ip-addresses
• custom DNS gateway(s)
• RFC MX lookup flow
• SMTP port number
• SMTP fail fast
• SMTP safe check
• event logger
• JSON serializer

Setting global configuration

To have an access for Truemail.configuration and gem configuration features, you must configure it first as in the example below:

…

Read global configuration

After successful configuration, you can read current Truemail configuration instance anywhere in your application.

…

Update global configuration

…

Reset global configuration

Also you can reset Truemail configuration.

Truemail.reset_configuration!
=> nil
Truemail.configuration
=> nil

Using custom independent configuration

Allows to use independent configuration for each validation/audition instance. When using this feature you do not need to have Truemail global configuration.

custom_configuration = Truemail::Configuration.new do |config|
  config.verifier_email = '[email protected]'
end

Truemail.validate('[email protected]', custom_configuration: custom_configuration)
Truemail.valid?('[email protected]', custom_configuration: custom_configuration)
Truemail.host_audit('[email protected]', custom_configuration: custom_configuration)

Please note, you should have global or custom configuration for use Truemail gem.

Validation features

Whitelist/Blacklist check

Whitelist/Blacklist check is zero validation level. You can define white and black emails/domains lists. It means that validation of email which contains whitelisted email or domain always will return true, and for blacklisted email or domain will return false.

Please note, other validations will not processed even if it was defined in validation_type_for.

Sequence of domain list check:

1. Whitelist check
2. Whitelist validation check
3. Blacklist check

Example of usage:

require 'truemail'

Truemail.configure do |config|
  config.verifier_email = '[email protected]'
  config.whitelisted_emails = %w[[email protected] [email protected]]
  config.blacklisted_emails = %w[[email protected] [email protected]]
  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

Whitelist case

When email in whitelist, validation type will be redefined. Validation result returns true

Truemail.validate('[email protected]')

#,
    configuration=#:mx},
     @verifier_domain="example.com",
     @verifier_email="[email protected]",
     @whitelist_validation=false,
     @whitelisted_domains=["white-domain.com", "somedomain.com"]>,
  @validation_type=:whitelist>

Whitelist validation case

require 'truemail'

Truemail.configure do |config|
  config.verifier_email = '[email protected]'
  config.whitelisted_domains = %w[white-domain.com]
  config.whitelist_validation = true
end

When email domain in whitelist and whitelist_validation is sets equal to true validation type will be passed to other validators. Validation of email which not contains whitelisted domain always will return false.

Email has whitelisted domain

Truemail.validate('[email protected]', with: :regex)

#,
    configuration=
    #,
  @validation_type=:regex>

Email hasn't whitelisted domain

Truemail.validate('[email protected]', with: :regex)

#,
    configuration=
    #,
  @validation_type=:blacklist>

Blacklist case

When email in blacklist, validation type will be redefined too. Validation result returns false.

Truemail.validate('[email protected]')

#,
    configuration=
    #,
  @validation_type=:blacklist>

Duplication case

Validation result for this email returns true, because it was found in whitelisted domains list first. Also validation_type for this case will be redefined.

Truemail.validate('[email protected]')

#,
    configuration=
    #,
  @validation_type=:whitelist>

Regex validation

Validation with regex pattern is the first validation level. It uses whitelist/blacklist check before running itself.

[Whitelist/Blacklist] -> [Regex validation]

By default this validation not performs strictly following RFC 5322 standard, so you can override Truemail default regex pattern if you want.

Example of usage:

With default regex pattern

require 'truemail'

Truemail.configure do |config|
  config.verifier_email = '[email protected]'
end

Truemail.validate('[email protected]', with: :regex)

=> #,
      configuration=
      #,
  @validation_type=:regex>

With custom regex pattern

You should define your custom regex pattern in a gem configuration before.

require 'truemail'

Truemail.configure do |config|
  config.verifier_email = '[email protected]'
  config.email_pattern = /regex_pattern/
end

Truemail.validate('[email protected]', with: :regex)

=> #,
      configuration=
      #,
  @validation_type=:regex>

MX validation

In fact it's DNS validation because it checks not MX records only. DNS validation is the second validation level, historically named as MX validation. It uses Regex validation before running itself. When regex validation has completed successfully then runs itself.

[Whitelist/Blacklist] -> [Regex validation] -> [MX validation]

Please note, Truemail MX validator not performs strict compliance of the RFC 5321 standard for best validation outcome.

RFC MX lookup flow

Truemail MX lookup based on RFC 5321. It consists of 3 substeps: MX, CNAME and A record resolvers. The point of each resolver is attempt to extract the mail servers from email domain. If at least one server exists that validation is successful. Iteration is processing until resolver returns true.

Example of usage:

require 'truemail'

Truemail.configure do |config|
  config.verifier_email = '[email protected]'
end

Truemail.validate('[email protected]', with: :mx)

=> #,
      configuration=
      #,
  @validation_type=:mx>

Not RFC MX lookup flow

Also Truemail has possibility to use not RFC MX lookup flow. It means that will be used only one MX resolver on the DNS validation layer. By default this option is disabled.

Example of usage:

require 'truemail'

Truemail.configure do |config|
  config.verifier_email = '[email protected]'
  config.not_rfc_mx_lookup_flow = true
end

Truemail.validate('[email protected]', with: :mx)

=> #,
      configuration=
      #,
  @validation_type=:mx>

MX blacklist validation

MX blacklist validation is the third validation level. This layer provides checking extracted mail server(s) IP address from MX validation with predefined blacklisted IP addresses list. It can be used as a part of DEA (disposable email address) validations.

[Whitelist/Blacklist] -> [Regex validation] -> [MX validation] -> [MX blackli