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:

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.
  # This parameter uses in mx lookup timeout error and smtp request (for cases when
  # there is one mx server).
  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.
  # Also you can skip validation by domain.
  # Available validation types: :regex, :mx, :mx_blacklist, :smtp
  # This configuration will be used over current or default validation type parameter
  # All of validations for 'somedomain.com' will be processed with regex validation only.
  # And all of validations for 'otherdomain.com' will be processed with mx validation only.
  # It is equal to empty hash by default.
  config.validation_type_for = { 'somedomain.com' => :regex, 'otherdomain.com' => :mx }

  # Optional parameter. Validation of email which contains whitelisted emails always will
  # return true. Other validations will not processed even if it was defined in validation_type_for
  # It is equal to empty array by default.
  config.whitelisted_emails = %w[user@somedomain1.com user@somedomain2.com]

  # Optional parameter. Validation of email which contains blacklisted emails always will
  # return false. Other validations will not processed even if it was defined in validation_type_for
  # It is equal to empty array by default.
  config.blacklisted_emails = %w[user@somedomain3.com user@somedomain4.com]

  # Optional parameter. Validation of email which contains whitelisted domain always will
  # return true. Other validations will not processed even if it was defined in validation_type_for
  # It is equal to empty array by default.
  config.whitelisted_domains = %w[somedomain1.com somedomain2.com]

  # Optional parameter. Validation of email which contains blacklisted domain always will
  # return false. Other validations will not processed even if it was defined in validation_type_for
  # It is equal to empty array by default.
  config.blacklisted_domains = %w[somedomain3.com somedomain4.com]

  # Optional parameter. With this option Truemail will validate email which contains whitelisted
  # domain only, i.e. if domain whitelisted, validation will passed to Regex, MX or SMTP validators.
  # Validation of email which not contains whitelisted domain always will return false.
  # It is equal false by default.
  config.whitelist_validation = true

  # Optional parameter. With this option Truemail will filter out unwanted mx servers via
  # predefined list of ip addr