README.md in truemail-1.2.1 vs README.md in truemail-1.3.0
- old
+ new
@@ -1,10 +1,10 @@
# Truemail
[](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 by regex pattern, presence of domain mx-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.
+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.
## Features
- Configurable validator, validate only what you need
- Zero runtime dependencies
@@ -32,22 +32,24 @@
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 MX records.
+**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
+### Configuration features
-#### Set configuration
+You can use global gem configuration or custom independent configuration.
-To have an access for ```Truemail.configuration``` and gem features, you must configure it first as in the example below:
+#### 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
require 'truemail'
Truemail.configure do |config|
# Required parameter. Must be an existing email on behalf of which verification will be performed
@@ -108,11 +110,11 @@
# By default this option is disabled, available for SMTP validation only.
config.smtp_safe_check = true
end
```
-#### Read configuration
+##### Read global configuration
After successful configuration, you can read current Truemail configuration instance anywhere in your application.
```ruby
Truemail.configuration
@@ -130,11 +132,11 @@
@verifier_domain="somedomain.com",
@verifier_email="verifier@example.com"
@smtp_safe_check=true>
```
-#### Update configuration
+##### Update global configuration
```ruby
Truemail.configuration.connection_timeout = 3
=> 3
Truemail.configuration.response_timeout = 4
@@ -156,21 +158,38 @@
@verifier_domain="somedomain.com",
@verifier_email="verifier@example.com",
@smtp_safe_check=true>
```
-#### Reset configuration
+##### Reset global configuration
Also you can reset Truemail configuration.
```ruby
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.
+
+```ruby
+custom_configuration = Truemail::Configuration.new do |config|
+ config.verifier_email = 'verifier@example.com'
+end
+
+Truemail.validate('email@example.com', custom_configuration: custom_configuration)
+Truemail.valid?('email@example.com', custom_configuration: custom_configuration)
+Truemail.host_audit('email@example.com', 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 list domains. It means that validation of email which contains whitelisted domain always will return ```true```, and for blacklisted domain will return ```false```.
@@ -208,10 +227,24 @@
email="email@white-domain.com",
domain=nil,
mail_servers=[],
errors={},
smtp_debug=nil>,
+ configuration=#<Truemail::Configuration:0x00005629f801bd28
+ @blacklisted_domains=["black-domain.com", "somedomain.com"],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={"somedomain.com"=>:mx},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com",
+ @whitelist_validation=false,
+ @whitelisted_domains=["white-domain.com", "somedomain.com"]>,
@validation_type=:whitelist>
```
##### Whitelist validation case
@@ -239,10 +272,25 @@
email="email@white-domain.com",
domain=nil,
mail_servers=[],
errors={},
smtp_debug=nil>,
+ configuration=
+ #<Truemail::Configuration:0x0000563f0d2605c8
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com",
+ @whitelist_validation=true,
+ @whitelisted_domains=["white-domain.com"]>,
@validation_type=:regex>
```
###### Email hasn't whitelisted domain
@@ -255,10 +303,25 @@
email="email@domain.com",
domain=nil,
mail_servers=[],
errors={},
smtp_debug=nil>,
+ configuration=
+ #<Truemail::Configuration:0x0000563f0cd82ab0
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com",
+ @whitelist_validation=true,
+ @whitelisted_domains=["white-domain.com"]>,
@validation_type=:blacklist>
```
##### Blacklist case
@@ -273,10 +336,25 @@
email="email@black-domain.com",
domain=nil,
mail_servers=[],
errors={},
smtp_debug=nil>,
+ configuration=
+ #<Truemail::Configuration:0x0000563f0d36f4f0
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com",
+ @whitelist_validation=true,
+ @whitelisted_domains=["white-domain.com"]>,
@validation_type=:blacklist>
```
##### Duplication case
@@ -291,10 +369,25 @@
email="email@somedomain.com",
domain=nil,
mail_servers=[],
errors={},
smtp_debug=nil>,
+ configuration=
+ #<Truemail::Configuration:0x0000563f0d3f8fc0
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com",
+ @whitelist_validation=true,
+ @whitelisted_domains=["white-domain.com"]>,
@validation_type=:whitelist>
```
#### Regex validation
@@ -325,10 +418,25 @@
success=true, email="email@example.com",
domain=nil,
mail_servers=[],
errors={},
smtp_debug=nil>,
+ configuration=
+ #<Truemail::Configuration:0x000055aa56a54d48
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com",
+ @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.
@@ -349,10 +457,25 @@
email="email@example.com",
domain=nil,
mail_servers=[],
errors={},
smtp_debug=nil>,
+ configuration=
+ #<Truemail::Configuration:0x0000560e58d80830
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/regex_pattern/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com",
+ @whitelist_validation=false,
+ @whitelisted_domains=[]>,
@validation_type=:regex>
```
#### MX validation
@@ -382,10 +505,25 @@
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([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @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
@@ -418,10 +556,25 @@
email="email@example.com",
domain="example.com",
mail_servers=["127.0.1.1", "127.0.1.2"],
errors={},
smtp_debug=nil>,
+ configuration=
+ #<Truemail::Configuration:0x00005615e87b9298
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @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 validation failed
=> #<Truemail::Validator:0x0000000002d5cee0
@result=
@@ -432,21 +585,13 @@
mail_servers=["127.0.1.1", "127.0.1.2"],
errors={:smtp=>"smtp error"},
smtp_debug=
[#<Truemail::Validate::Smtp::Request:0x0000000002d49b10
@configuration=
- #<Truemail::Configuration:0x0000000002d49930
+ #<Truemail::Validate::Smtp::Request::Configuration:0x00005615e8d21848
@connection_timeout=2,
- @email_pattern=/regex_pattern/,
- @smtp_error_body_pattern=/regex_pattern/,
@response_timeout=2,
- @connection_attempts=2,
- @smtp_safe_check=false,
- @validation_type_by_domain={},
- @whitelisted_domains=[],
- @whitelist_validation=false,
- @blacklisted_domains=[],
@verifier_domain="example.com",
@verifier_email="verifier@example.com">,
@email="email@example.com",
@host="127.0.1.1",
@attempts=nil,
@@ -462,10 +607,25 @@
#<Net::SMTP::Response:0x0000000002d5a618
@status="250",
@string="250 OK\n">,
rcptto=false,
errors={:rcptto=>"550 User not found\n"}>>]>,
+ configuration=
+ #<Truemail::Configuration:0x00005615e87b9298
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @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>
```
With ```smtp_safe_check = true```
@@ -489,37 +649,44 @@
mail_servers=["127.0.1.1", "127.0.1.2"],
errors={},
smtp_debug=
[#<Truemail::Validate::Smtp::Request:0x0000000002c95d40
@configuration=
- #<Truemail::Configuration:0x0000000002c95b38
- @connection_timeout=2,
- @email_pattern=/regex_pattern/,
- @smtp_error_body_pattern=/regex_pattern/,
- @response_timeout=2,
- @connection_attempts=2,
- @smtp_safe_check=true,
- @validation_type_by_domain={},
- @whitelisted_domains=[],
- @whitelist_validation=false,
- @blacklisted_domains=[],
- @verifier_domain="example.com",
- @verifier_email="verifier@example.com">,
- @email="email@example.com",
- @host="127.0.1.1",
- @attempts=nil,
- @response=
- #<struct Truemail::Validate::Smtp::Response
- port_opened=true,
- connection=false,
- helo=
- #<Net::SMTP::Response:0x0000000002c934c8
- @status="250",
- @string="250 127.0.1.1\n">,
- mailfrom=false,
- rcptto=nil,
- errors={:mailfrom=>"554 5.7.1 Client host blocked\n", :connection=>"server dropped connection after response"}>>,]>,
+ #<Truemail::Validate::Smtp::Request::Configuration:0x00005615e8d21848
+ @connection_timeout=2,
+ @response_timeout=2,
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com">,
+ @email="email@example.com",
+ @host="127.0.1.1",
+ @attempts=nil,
+ @response=
+ #<struct Truemail::Validate::Smtp::Response
+ port_opened=true,
+ connection=false,
+ helo=
+ #<Net::SMTP::Response:0x0000000002c934c8
+ @status="250",
+ @string="250 127.0.1.1\n">,
+ mailfrom=false,
+ rcptto=nil,
+ errors={:mailfrom=>"554 5.7.1 Client host blocked\n", :connection=>"server dropped connection after response"}>>,]>,
+ configuration=
+ #<Truemail::Configuration:0x00005615e87b9298
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @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 validation failed
=> #<Truemail::Validator:0x0000000002d5cee0
@result=
@@ -530,21 +697,13 @@
mail_servers=["127.0.1.1", "127.0.1.2"],
errors={:smtp=>"smtp error"},
smtp_debug=
[#<Truemail::Validate::Smtp::Request:0x0000000002d49b10
@configuration=
- #<Truemail::Configuration:0x0000000002d49930
+ #<Truemail::Validate::Smtp::Request::Configuration:0x00005615e8d21848
@connection_timeout=2,
- @email_pattern=/regex_pattern/,
- @smtp_error_body_pattern=/regex_pattern/,
@response_timeout=2,
- @connection_attempts=2,
- @smtp_safe_check=true,
- @validation_type_by_domain={},
- @whitelisted_domains=[],
- @whitelist_validation=false,
- @blacklisted_domains=[],
@verifier_domain="example.com",
@verifier_email="verifier@example.com">,
@email="email@example.com",
@host="127.0.1.1",
@attempts=nil,
@@ -557,10 +716,25 @@
@status="250",
@string="250 127.0.1.1 Hello example.com\n">,
mailfrom=#<Net::SMTP::Response:0x0000000002d5a618 @status="250", @string="250 OK\n">,
rcptto=false,
errors={:rcptto=>"550 User not found\n"}>>]>,
+ configuration=
+ #<Truemail::Configuration:0x00005615e87b9298
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @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>
```
### Host audit features
@@ -574,17 +748,47 @@
Truemail.host_audit
# Everything is good
=> #<Truemail::Auditor:0x00005580df358828
@result=
#<struct Truemail::Auditor::Result
- warnings={}>>
+ warnings={}>,
+ configuration=
+ #<Truemail::Configuration:0x00005615e86327a8
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com",
+ @whitelist_validation=false,
+ @whitelisted_domains=[]>
# Has PTR warning
=> #<Truemail::Auditor:0x00005580df358828
@result=
#<struct Truemail::Auditor::Result
warnings=
- {:ptr=>"ptr record does not reference to current verifier domain"}>>
+ {:ptr=>"ptr record does not reference to current verifier domain"}>,
+ configuration=
+ #<Truemail::Configuration:0x00005615e86327a8
+ @blacklisted_domains=[],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @email_pattern=/(?=\A.{6,255}\z)(\A([a-zA-Z0-9]+[\w|\-|\.|\+]*)@((?i-mx:[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,63}))\z)/,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com",
+ @whitelist_validation=false,
+ @whitelisted_domains=[]>
```
### Truemail helpers
#### .valid?