README.md in truemail-1.6.1 vs README.md in truemail-1.7.0

- old
+ new

@@ -6,10 +6,11 @@ ## Table of Contents - [Synopsis](#synopsis) - [Features](#features) +- [Requirements](#requirements) - [Installation](#installation) - [Usage](#usage) - [Configuration features](#configuration-features) - [Setting global configuration](#setting-global-configuration) - [Read global configuration](#read-global-configuration) @@ -24,10 +25,12 @@ - [Duplication case](#duplication-case) - [Regex validation](#regex-validation) - [With default regex pattern](#with-default-regex-pattern) - [With custom regex pattern](#with-custom-regex-pattern) - [DNS (MX) validation](#mx-validation) + - [RFC MX lookup flow](#rfc-mx-lookup-flow) + - [Not RFC MX lookup flow](#not-rfc-mx-lookup-flow) - [SMTP validation](#smtp-validation) - [SMTP safe check disabled](#smtp-safe-check-disabled) - [SMTP safe check enabled](#smtp-safe-check-enabled) - [Event logger](#event-logger) - [Available tracking events](#available-tracking-events) @@ -67,25 +70,33 @@ - Whitelist/blacklist validation layers - Simple SMTP debugger - Event logger - JSON serializer +## Requirements + +Ruby MRI 2.5.0+ + ## Installation Add this line to your application's Gemfile: ```ruby gem 'truemail' ``` And then execute: - $ bundle +```bash +bundle +``` Or install it yourself as: - $ gem install truemail +```bash +gem install truemail +``` ## Usage ### Configuration features @@ -166,10 +177,15 @@ # 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 = ['somedomain1.com', 'somedomain2.com'] + # Optional parameter. This option will provide to use not RFC MX lookup flow. + # It means that MX and Null MX records will be cheked on the DNS validation layer only. + # By default this option is disabled. + config.not_rfc_mx_lookup_flow = true + # Optional parameter. This option will be parse bodies of SMTP errors. It will be helpful # if SMTP server does not return an exact answer that the email does not exist # By default this option is disabled, available for SMTP validation only. config.smtp_safe_check = true @@ -196,11 +212,12 @@ @validation_type_by_domain={}, @whitelisted_domains=[], @whitelist_validation=true, @blacklisted_domains=[], @verifier_domain="somedomain.com", - @verifier_email="verifier@example.com" + @verifier_email="verifier@example.com", + @not_rfc_mx_lookup_flow=true, @smtp_safe_check=true, @logger=#<Truemail::Logger:0x0000557f837450b0 @event=:all, @file="/home/app/log/truemail.log", @stdout=true>> ``` @@ -225,10 +242,11 @@ @whitelisted_domains=[], @whitelist_validation=true, @blacklisted_domains=[], @verifier_domain="somedomain.com", @verifier_email="verifier@example.com", + @not_rfc_mx_lookup_flow=true, @smtp_safe_check=true, @logger=#<Truemail::Logger:0x0000557f837450b0 @event=:all, @file="/home/app/log/truemail.log", @stdout=true>> ``` @@ -307,10 +325,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={"somedomain.com"=>:mx}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @@ -353,10 +372,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=true, @@ -384,10 +404,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=true, @@ -417,10 +438,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=true, @@ -450,10 +472,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=true, @@ -499,10 +522,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @@ -540,10 +564,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/regex_pattern/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @@ -557,12 +582,16 @@ ```code [Whitelist/Blacklist] -> [Regex validation] -> [MX validation] ``` -Please note, Truemail MX validator not performs strict compliance of the [RFC 5321](https://tools.ietf.org/html/rfc5321#section-5) standard for best validation outcome. +Please note, Truemail MX validator [not performs](https://github.com/rubygarage/truemail/issues/26) strict compliance of the [RFC 5321](https://tools.ietf.org/html/rfc5321#section-5) standard for best validation outcome. +##### RFC MX lookup flow + +[Truemail MX lookup](https://slides.com/vladislavtrotsenko/truemail#/0/9) 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: ```ruby require 'truemail' @@ -588,19 +617,64 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @whitelisted_domains=[]>, @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: + +```ruby +require 'truemail' + +Truemail.configure do |config| + config.verifier_email = 'verifier@example.com' + config.not_rfc_mx_lookup_flow = true +end + +Truemail.validate('email@example.com', with: :mx) + +=> #<Truemail::Validator:0x000055590c9c1c50 + @result= + #<struct Truemail::Validator::Result + success=true, + email="email@example.com", + domain="example.com", + mail_servers=["127.0.1.1", "127.0.1.2"], + errors={}, + smtp_debug=nil>, + configuration= + #<Truemail::Configuration:0x0000559b6e44af70 + @blacklisted_domains=[], + @connection_attempts=2, + @connection_timeout=2, + @default_validation_type=:smtp, + @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, + @response_timeout=2, + @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=true, + @smtp_safe_check=false, + @validation_type_by_domain={}, + @verifier_domain="example.com", + @verifier_email="verifier@example.com", + @whitelist_validation=false, + @whitelisted_domains=[]>, + @validation_type=:mx> +``` + #### SMTP validation SMTP validation is a final, third validation level. This type of validation tries to check real existence of email account on a current email server. This validation runs a chain of previous validations and if they're complete successfully then runs itself. ```code @@ -609,11 +683,11 @@ If total count of MX servers is equal to one, ```Truemail::Smtp``` validator will use value from ```Truemail.configuration.connection_attempts``` as connection attempts. By default it's equal 2. By default, you don't need pass with-parameter to use it. Example of usage is specified below: -###### SMTP safe check disabled +##### SMTP safe check disabled With ```smtp_safe_check = false``` ```ruby require 'truemail' @@ -641,10 +715,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @@ -692,22 +767,22 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @whitelisted_domains=[]>, @validation_type=:smtp> ``` +##### SMTP safe check enabled -###### SMTP safe check enabled - With ```smtp_safe_check = true``` ```ruby require 'truemail' @@ -756,10 +831,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @@ -804,10 +880,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @@ -893,10 +970,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @@ -915,10 +993,11 @@ @connection_timeout=2, @default_validation_type=:smtp, @email_pattern=/(?=\A.{6,255}\z)(\A([\p{L}0-9]+[\w|\-|\.|\+]*)@((?i-mx:[\p{L}0-9]+([\-\.]{1}[\p{L}0-9]+)*\.[\p{L}]{2,63}))\z)/, @response_timeout=2, @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i, + @not_rfc_mx_lookup_flow=false, @smtp_safe_check=false, @validation_type_by_domain={}, @verifier_domain="example.com", @verifier_email="verifier@example.com", @whitelist_validation=false, @@ -1006,24 +1085,21 @@ end end ``` --- + ## Truemail family All Truemail extensions: https://github.com/truemail-rb -### truemail server - -Lightweight rack based web API wrapper for Truemail, https://github.com/truemail-rb/truemail-rack - -### truemail-rack-docker-image - -Lightweight rack based web API dockerized image :whale: of [Truemail server](https://github.com/truemail-rb/truemail-rack) hosted on [dockerhub](https://hub.docker.com/r/truemail/truemail-rack), https://github.com/truemail-rb/truemail-rack-docker-image - -### truemail-rspec - -gem `truemail-rspec` - Truemail configuration and validator RSpec helpers, https://github.com/truemail-rb/truemail-rspec +| Name | Type | Description | +| --- | --- | --- | +| [truemail server](https://github.com/truemail-rb/truemail-rack) | ruby app | Lightweight rack based web API wrapper for Truemail | +| [truemail-rack-docker](https://github.com/truemail-rb/truemail-rack-docker-image) | docker image | Lightweight rack based web API [dockerized image](https://hub.docker.com/r/truemail/truemail-rack) :whale: of Truemail server | +| [truemail-ruby-client](https://github.com/truemail-rb/truemail-ruby-client) | ruby gem | Truemail web API client library for Ruby | +| [truemail-crystal-client](https://github.com/truemail-rb/truemail-crystal-client) | crystal shard | Truemail web API client library for Crystal | +| [truemail-rspec](https://github.com/truemail-rb/truemail-rspec) | ruby gem | Truemail configuration and validator RSpec helpers | ## Contributing Bug reports and pull requests are welcome on GitHub at https://github.com/rubygarage/truemail. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. Please check the [open tikets](https://github.com/rubygarage/truemail/issues). Be shure to follow Contributor Code of Conduct below and our [Contributing Guidelines](CONTRIBUTING.md).