README.md in truemail-1.3.0 vs README.md in truemail-1.4.0
- old
+ new
@@ -1,18 +1,68 @@
-# Truemail
+# <img src='https://repository-images.githubusercontent.com/173723932/6dffee00-e88e-11e9-94b6-c97aacc0df00' height='250' alt='Truemail - configurable plain Ruby email validator' />
[](https://codeclimate.com/github/rubygarage/truemail/maintainability) [](https://codeclimate.com/github/rubygarage/truemail/test_coverage) [](https://circleci.com/gh/rubygarage/truemail/tree/master) [](https://badge.fury.io/rb/truemail) [](https://rubygems.org/gems/truemail) [](CODE_OF_CONDUCT.md)
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. Also Truemail gem allows performing an audit of the host in which runs.
+## Table of Contents
+
+- [Synopsis](#synopsis)
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+ - [Configuration features](#configuration-features)
+ - [Setting global configuration](#setting-global-configuration)
+ - [Read global configuration](#read-global-configuration)
+ - [Update global configuration](#update-global-configuration)
+ - [Reset global configuration](#reset-global-configuration)
+ - [Using custom independent configuration](#using-custom-independent-configuration)
+ - [Validation features](#validation-features)
+ - [Whitelist/Blacklist check](#whitelist-blacklist-check)
+ - [Whitelist case](#whitelist-case)
+ - [Whitelist validation case](#whitelist-validation-case)
+ - [Blacklist case](#blacklist-case)
+ - [Duplication case](#duplication-case)
+ - [Regex validation](#regex-validation)
+ - [With default regex pattern](#with-default-regex-pattern)
+ - [With custom regex pattern](#with-custom-regex-pattern)
+ - [MX validation](#mx-validation)
+ - [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)
+ - [JSON serializer](#json-serializer)
+ - [Host audit features](#host-audit-features)
+ - [PTR audit](#ptr-audit)
+ - [Truemail helpers](#truemail-helpers)
+ - [.valid?](#valid)
+ - [Test environment](#test-environment)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+- [Versioning](#versioning)
+- [Changelog](CHANGELOG.md)
+
+## 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. You can get more information about email validation techniques in our [blog](https://rubygarage.org/blog/how-to-validate-emails).
+
+**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.
+
## Features
- Configurable validator, validate only what you need
- Zero runtime dependencies
-- Has whitelist/blacklist
-- Has simple SMTP debugger
-- 100% test coverage
+- Whitelist/blacklist validation layers
+- Simple SMTP debugger
+- Event logger
+- JSON serializer
## Installation
Add this line to your application's Gemfile:
@@ -26,26 +76,33 @@
Or install it yourself as:
$ gem install truemail
-## Email Validation Methods
-
-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. You can get more information about email validation techniques in our [blog](https://rubygarage.org/blog/how-to-validate-emails).
-
-**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.
-
## Usage
### Configuration features
-You can use global gem configuration or custom independent configuration.
+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 domains
+- whitelist validation
+- blacklisted domains
+- 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:
```ruby
@@ -107,10 +164,15 @@
# 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
+
+ # Optional parameter. This option will enable tracking events. You can print tracking events to
+ # stdout, write to file or both of these. Tracking event by default is :error
+ # Available tracking event: :all, :unrecognized_error, :recognized_error, :error
+ config.logger = { tracking_event: :all, stdout: true, log_absolute_path: '/home/app/log/truemail.log' }
end
```
##### Read global configuration
@@ -129,11 +191,13 @@
@whitelisted_domains=[],
@whitelist_validation=true,
@blacklisted_domains=[],
@verifier_domain="somedomain.com",
@verifier_email="verifier@example.com"
- @smtp_safe_check=true>
+ @smtp_safe_check=true,
+ @logger=#<Truemail::Logger:0x0000557f837450b0
+ @event=:all, @file="/home/app/log/truemail.log", @stdout=true>>
```
##### Update global configuration
```ruby
@@ -155,11 +219,13 @@
@whitelisted_domains=[],
@whitelist_validation=true,
@blacklisted_domains=[],
@verifier_domain="somedomain.com",
@verifier_email="verifier@example.com",
- @smtp_safe_check=true>
+ @smtp_safe_check=true,
+ @logger=#<Truemail::Logger:0x0000557f837450b0
+ @event=:all, @file="/home/app/log/truemail.log", @stdout=true>>
```
##### Reset global configuration
Also you can reset Truemail configuration.
@@ -399,11 +465,11 @@
By default this validation not performs strictly following [RFC 5322](https://www.ietf.org/rfc/rfc5322.txt) standard, so you can override Truemail default regex pattern if you want.
Example of usage:
-1. With default regex pattern
+##### With default regex pattern
```ruby
require 'truemail'
Truemail.configure do |config|
@@ -436,12 +502,14 @@
@whitelist_validation=false,
@whitelisted_domains=[]>,
@validation_type=:regex>
```
-2. With custom regex pattern. You should define your custom regex pattern in a gem configuration before.
+##### With custom regex pattern
+You should define your custom regex pattern in a gem configuration before.
+
```ruby
require 'truemail'
Truemail.configure do |config|
config.verifier_email = 'verifier@example.com'
@@ -535,10 +603,12 @@
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
+
With ```smtp_safe_check = false```
```ruby
require 'truemail'
@@ -625,10 +695,13 @@
@whitelist_validation=false,
@whitelisted_domains=[]>,
@validation_type=:smtp>
```
+
+###### SMTP safe check enabled
+
With ```smtp_safe_check = true```
```ruby
require 'truemail'
@@ -732,9 +805,65 @@
@verifier_domain="example.com",
@verifier_email="verifier@example.com",
@whitelist_validation=false,
@whitelisted_domains=[]>,
@validation_type=:smtp>
+```
+
+### Event logger
+
+Truemail gem allows to output tracking events to stdout/file or both of these. Please note, at least one of the outputs must exist. Tracking event by default is `:error`
+
+```ruby
+Truemail.configure do |config|
+ config.logger = { tracking_event: :all, stdout: true, log_absolute_path: '/home/app/log/truemail.log' }
+end
+```
+
+#### Available tracking events
+
+- `:all`, all detected events including success validation cases
+- `:unrecognized_error`, unrecognized errors only (when `smtp_safe_check = true` and SMTP server does not return an exact answer that the email does not exist)
+- `:recognized_error`, recognized errors only
+- `:error`, recognized and unrecognized errors only
+
+### JSON serializer
+
+Truemail has built in JSON serializer for `Truemail::Validator` instance, so you can represent your email validation result as json.
+
+```ruby
+Truemail::Log::Serializer::Json.call(Truemail.validate('nonexistent_email@bestweb.com.ua'))
+
+=>
+# Serialized Truemail::Validator instance
+{
+ "date": "2019-10-28 10:15:51 +0200",
+ "email": "nonexistent_email@bestweb.com.ua",
+ "validation_type": "smtp",
+ "success": false,
+ "errors": {
+ "smtp": "smtp error"
+ },
+ "smtp_debug": [
+ {
+ "mail_host": "213.180.193.89",
+ "port_opened": true,
+ "connection": true,
+ "errors": {
+ "rcptto": "550 5.7.1 No such user!\n"
+ }
+ }
+ ],
+ "configuration": {
+ "validation_type_by_domain": null,
+ "whitelist_validation": false,
+ "whitelisted_domains": null,
+ "blacklisted_domains": null,
+ "smtp_safe_check": false,
+ "email_pattern": "default gem value",
+ "smtp_error_body_pattern": "default gem value"
+ }
+}
```
### Host audit features
Truemail gem allows performing an audit of the host in which runs. Only PTR record audit performs for today.