README.md in truemail-2.3.4 vs README.md in truemail-2.4.0
- old
+ new
@@ -37,10 +37,11 @@
- [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)
+ - [MX blacklist validation](#mx-blacklist-validation)
- [SMTP validation](#smtp-validation)
- [SMTP fail fast enabled](#smtp-fail-fast-enabled)
- [SMTP safe check disabled](#smtp-safe-check-disabled)
- [SMTP safe check enabled](#smtp-safe-check-enabled)
- [Host audit features](#host-audit-features)
@@ -130,10 +131,11 @@
- default validation type
- validation type for domains
- whitelisted domains
- whitelist validation
- blacklisted domains
+- blacklisted mx ip-addresses
- custom DNS gateway(s)
- RFC MX lookup flow
- SMTP fail fast
- SMTP safe check
- event logger
@@ -198,12 +200,17 @@
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
# It is equal to empty array by default.
- config.blacklisted_domains = ['somedomain1.com', 'somedomain2.com']
+ config.blacklisted_domains = ['somedomain3.com', 'somedomain4.com']
+ # Optional parameter. With this option Truemail will filter out unwanted mx servers via
+ # predefined list of ip addresses. It can be used as a part of DEA (disposable email
+ # address) validations. It is equal to empty array by default.
+ config.blacklisted_mx_ip_addresses = ['1.1.1.1', '2.2.2.2']
+
# Optional parameter. This option will provide to use custom DNS gateway when Truemail
# interacts with DNS. Valid port numbers are in the range 1-65535. If you won't specify
# nameserver's ports Truemail will use default DNS TCP/UDP port 53. By default Truemail
# uses DNS gateway from system settings and this option is equal to empty array.
config.dns = ['10.0.0.1', '10.0.0.2:54']
@@ -243,15 +250,17 @@
@connection_timeout=1,
@email_pattern=/regex_pattern/,
@smtp_error_body_pattern=/regex_pattern/,
@response_timeout=1,
@connection_attempts=3,
- @validation_type_by_domain={},
- @whitelisted_domains=[],
+ @default_validation_type=:mx,
+ @validation_type_by_domain={"somedomain.com" => :regex, "otherdomain.com" => :mx},
+ @whitelisted_domains=["somedomain1.com", "somedomain2.com"],
@whitelist_validation=true,
- @blacklisted_domains=[],
- @dns=[],
+ @blacklisted_domains=["somedomain3.com", "somedomain4.com"],
+ @blacklisted_mx_ip_addresses=["1.1.1.1", "2.2.2.2"],
+ @dns=["10.0.0.1", "10.0.0.2:54"],
@verifier_domain="somedomain.com",
@verifier_email="verifier@example.com",
@not_rfc_mx_lookup_flow=true,
@smtp_fail_fast=true,
@smtp_safe_check=true,
@@ -274,15 +283,17 @@
@connection_timeout=3,
@email_pattern=/regex_pattern/,
@smtp_error_body_pattern=/regex_pattern/,
@response_timeout=4,
@connection_attempts=1,
- @validation_type_by_domain={},
- @whitelisted_domains=[],
+ @default_validation_type=:mx,
+ @validation_type_by_domain={"somedomain.com" => :regex, "otherdomain.com" => :mx},
+ @whitelisted_domains=["somedomain1.com", "somedomain2.com"],
@whitelist_validation=true,
- @blacklisted_domains=[],
- @dns=[],
+ @blacklisted_domains=["somedomain3.com", "somedomain4.com"],
+ @blacklisted_mx_ip_addresses=["1.1.1.1", "2.2.2.2"],
+ @dns=["10.0.0.1", "10.0.0.2:54"],
@verifier_domain="somedomain.com",
@verifier_email="verifier@example.com",
@not_rfc_mx_lookup_flow=true,
@smtp_fail_fast=true,
@smtp_safe_check=true,
@@ -359,10 +370,11 @@
mail_servers=[],
errors={},
smtp_debug=nil>,
configuration=#<Truemail::Configuration:0x00005629f801bd28
@blacklisted_domains=["black-domain.com", "somedomain.com"],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -407,10 +419,11 @@
errors={},
smtp_debug=nil>,
configuration=
#<Truemail::Configuration:0x0000563f0d2605c8
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -441,10 +454,11 @@
errors={},
smtp_debug=nil>,
configuration=
#<Truemail::Configuration:0x0000563f0cd82ab0
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -461,11 +475,11 @@
@validation_type=:blacklist>
```
##### Blacklist case
-When email in blacklist, validation type will be redefined too. Validation result returns ```false```
+When email in blacklist, validation type will be redefined too. Validation result returns `false`
```ruby
Truemail.validate('email@black-domain.com')
#<Truemail::Validator:0x000023y8429f3493
@@ -477,10 +491,11 @@
errors={},
smtp_debug=nil>,
configuration=
#<Truemail::Configuration:0x0000563f0d36f4f0
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -513,10 +528,11 @@
errors={},
smtp_debug=nil>,
configuration=
#<Truemail::Configuration:0x0000563f0d3f8fc0
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -565,10 +581,11 @@
errors={},
smtp_debug=nil>,
configuration=
#<Truemail::Configuration:0x000055aa56a54d48
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -609,10 +626,11 @@
errors={},
smtp_debug=nil>,
configuration=
#<Truemail::Configuration:0x0000560e58d80830
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@connection_attempts=2,
@connection_timeout=2,
@default_validation_type=:smtp,
@email_pattern=/regex_pattern/,
@@ -664,10 +682,11 @@
errors={},
smtp_debug=nil>,
configuration=
#<Truemail::Configuration:0x0000559b6e44af70
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -710,10 +729,11 @@
errors={},
smtp_debug=nil>,
configuration=
#<Truemail::Configuration:0x0000559b6e44af70
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -728,16 +748,67 @@
@whitelist_validation=false,
@whitelisted_domains=[]>,
@validation_type=:mx>
```
+#### MX blacklist validation
+
+MX blacklist validation is the third validation level. This layer provides checking extracted mail server(s) IP address from MX validation with predefined blacklisted IP addresses list. It can be used as a part of DEA ([disposable email address](https://en.wikipedia.org/wiki/Disposable_email_address)) validations.
+
+```code
+[Whitelist/Blacklist] -> [Regex validation] -> [MX validation] -> [MX blacklist validation]
+```
+
+Example of usage:
+
+```ruby
+require 'truemail'
+
+Truemail.configure do |config|
+ config.verifier_email = 'verifier@example.com'
+ config.blacklisted_mx_ip_addresses = ['127.0.1.2']
+end
+
+Truemail.validate('email@example.com', with: :mx_blacklist)
+
+=> #<Truemail::Validator:0x00007fca0c8aea70
+ @result=
+ #<struct Truemail::Validator::Result
+ success=false,
+ email="email@example.com",
+ domain="example.com",
+ mail_servers=["127.0.1.1", "127.0.1.2"],
+ errors={:mx_blacklist=>"blacklisted mx server ip address"},
+ smtp_debug=nil,
+ configuration=
+ #<Truemail::Configuration:0x00007fca0c8aeb38
+ @blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=["127.0.1.2"],
+ @connection_attempts=2,
+ @connection_timeout=2,
+ @default_validation_type=:smtp,
+ @dns=[],
+ @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)/,
+ @not_rfc_mx_lookup_flow=false,
+ @response_timeout=2,
+ @smtp_error_body_pattern=/(?=.*550)(?=.*(user|account|customer|mailbox)).*/i,
+ @smtp_fail_fast=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_blacklist>
+```
+
#### 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.
+SMTP validation is a final, fourth 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
-[Whitelist/Blacklist] -> [Regex validation] -> [MX validation] -> [SMTP validation]
+[Whitelist/Blacklist] -> [Regex validation] -> [MX validation] -> [MX blacklist validation] -> [SMTP validation]
```
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:
@@ -785,10 +856,11 @@
rcptto=nil,
errors={}>>],
configuration=
#<Truemail::Configuration:0x00007fdc4504f5c8
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -829,10 +901,11 @@
errors={},
smtp_debug=nil>,
configuration=
#<Truemail::Configuration:0x00005615e87b9298
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -880,10 +953,11 @@
rcptto=false,
errors={:rcptto=>"550 User not found\n"}>>]>,
configuration=
#<Truemail::Configuration:0x00005615e87b9298
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -943,10 +1017,11 @@
rcptto=nil,
errors={:mailfrom=>"554 5.7.1 Client host blocked\n", :connection=>"server dropped connection after response"}>>,]>,
configuration=
#<Truemail::Configuration:0x00005615e87b9298
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -991,10 +1066,11 @@
rcptto=false,
errors={:rcptto=>"550 User not found\n"}>>]>,
configuration=
#<Truemail::Configuration:0x00005615e87b9298
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -1040,10 +1116,11 @@
current_host_ip="127.0.0.1",
warnings={}>,
configuration=
#<Truemail::Configuration:0x00005615e86327a8
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -1068,10 +1145,11 @@
:ptr=>"PTR-record does not reference to current verifier domain"
},
configuration=
#<Truemail::Configuration:0x00005615e86327a8
@blacklisted_domains=[],
+ @blacklisted_mx_ip_addresses=[],
@dns=[],
@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)/,
@@ -1121,10 +1199,11 @@
"warnings": {
"dns": "A-record of verifier domain not refers to current host ip address", "ptr": "PTR-record does not reference to current verifier domain"
},
"configuration": {
"blacklisted_domains": null,
+ "blacklisted_mx_ip_addresses": null,
"dns": null,
"email_pattern": "default gem value",
"not_rfc_mx_lookup_flow": false,
"smtp_error_body_pattern": "default gem value",
"smtp_fail_fast": false,
@@ -1161,10 +1240,11 @@
}
}
],
"configuration": {
"blacklisted_domains": null,
+ "blacklisted_mx_ip_addresses": null,
"dns": null,
"email_pattern": "default gem value",
"not_rfc_mx_lookup_flow": false,
"smtp_error_body_pattern": "default gem value",
"smtp_fail_fast": false,
@@ -1203,10 +1283,11 @@
"warnings": {
"dns": "A-record of verifier domain not refers to current host ip address", "ptr": "PTR-record does not reference to current verifier domain"
},
"configuration": {
"blacklisted_domains": null,
+ "blacklisted_mx_ip_addresses": null,
"dns": null,
"email_pattern": "default gem value",
"not_rfc_mx_lookup_flow": false,
"smtp_error_body_pattern": "default gem value",
"smtp_fail_fast": false,
@@ -1240,9 +1321,10 @@
}
}
],
"configuration": {
"blacklisted_domains": null,
+ "blacklisted_mx_ip_addresses": null,
"dns": null,
"email_pattern": "default gem value",
"not_rfc_mx_lookup_flow": false,
"smtp_error_body_pattern": "default gem value",
"smtp_fail_fast": false,