README.md in truemail-1.1.0 vs README.md in truemail-1.2.0
- old
+ new
@@ -1,8 +1,8 @@
# Truemail
-[](https://codeclimate.com/github/rubygarage/truemail/maintainability) [](https://codeclimate.com/github/rubygarage/truemail/test_coverage) [](https://badge.fury.io/rb/truemail) [](https://circleci.com/gh/rubygarage/truemail/tree/master) [](CODE_OF_CONDUCT.md)
+[](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.
## Features
@@ -88,11 +88,16 @@
# 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
config.whitelisted_domains = ['somedomain1.com', 'somedomain2.com']
- # Optional parameter. Validation of email which contains whitelisted domain always will
+ # 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.
+ config.whitelist_validation = true
+
+ # 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
config.blacklisted_domains = ['somedomain1.com', 'somedomain2.com']
# 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
@@ -114,10 +119,11 @@
@smtp_error_body_pattern=/regex_pattern/,
@response_timeout=1,
@connection_attempts=3,
@validation_type_by_domain={},
@whitelisted_domains=[],
+ @whitelist_validation=true,
@blacklisted_domains=[],
@verifier_domain="somedomain.com",
@verifier_email="verifier@example.com"
@smtp_safe_check=true>
```
@@ -139,10 +145,11 @@
@smtp_error_body_pattern=/regex_pattern/,
@response_timeout=4,
@connection_attempts=1,
@validation_type_by_domain={},
@whitelisted_domains=[],
+ @whitelist_validation=true,
@blacklisted_domains=[],
@verifier_domain="somedomain.com",
@verifier_email="verifier@example.com",
@smtp_safe_check=true>
```
@@ -166,11 +173,12 @@
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. Blacklist check
+2. Whitelist validation check
+3. Blacklist check
Example of usage:
```ruby
require 'truemail'
@@ -199,10 +207,57 @@
errors={},
smtp_debug=nil>,
@validation_type=:whitelist>
```
+##### Whitelist validation case
+
+```ruby
+require 'truemail'
+
+Truemail.configure do |config|
+ config.verifier_email = 'verifier@example.com'
+ config.whitelisted_domains = ['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
+
+```ruby
+Truemail.validate('email@white-domain.com', with: :regex)
+
+#<Truemail::Validator:0x000055b8429f3490
+ @result=#<struct Truemail::Validator::Result
+ success=true,
+ email="email@white-domain.com",
+ domain=nil,
+ mail_servers=[],
+ errors={},
+ smtp_debug=nil>,
+ @validation_type=:regex>
+```
+
+###### Email hasn't whitelisted domain
+
+```ruby
+Truemail.validate('email@domain.com', with: :regex)
+
+#<Truemail::Validator:0x000055b8429f3490
+ @result=#<struct Truemail::Validator::Result
+ success=false,
+ email="email@domain.com",
+ domain=nil,
+ mail_servers=[],
+ errors={},
+ smtp_debug=nil>,
+ @validation_type=:blacklist>
+```
+
##### Blacklist case
When email in blacklist, validation type will be redefined too. Validation result returns ```false```
```ruby
@@ -382,10 +437,11 @@
@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",
@@ -438,10 +494,11 @@
@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",
@@ -478,10 +535,11 @@
@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",
@@ -551,13 +609,9 @@
config.before { allow(Truemail).to receive_message_chain(:validate, :result, :valid?).and_return(true) }
end
```
---
-## ToDo
-
-Fail validations logger
-
## 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).
## License