README.md in truemail-0.1.1.3 vs README.md in truemail-0.1.2
- 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/develop)
+[](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)
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.
## Installation
@@ -37,10 +37,12 @@
#### Set configuration
To have an access for ```Truemail.configuration``` and gem 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
config.verifier_email = 'verifier@example.com'
# Optional parameter. Must be an existing domain on behalf of which verification will be performed.
@@ -59,10 +61,15 @@
# Optional parameter. You can predefine which type of validation will be used for domains.
# Available validation types: :regex, :mx, :smtp
# This configuration will be used over current or default validation type parameter
# All of validations for 'somedomain.com' will be processed with mx validation only
config.validation_type_for = { 'somedomain.com' => :mx }
+
+ # 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
end
```
#### Read configuration
@@ -75,11 +82,12 @@
@connection_timeout=1,
@email_pattern=/regex_pattern/,
@response_timeout=1,
@validation_type_by_domain={},
@verifier_domain="somedomain.com",
- @verifier_email="verifier@example.com">
+ @verifier_email="verifier@example.com"
+ @smtp_safe_check=true>
```
#### Update configuration
```ruby
@@ -93,11 +101,12 @@
@connection_timeout=3,
@email_pattern=/regex_pattern/,
@response_timeout=4,
@validation_type_by_domain={},
@verifier_domain="somedomain.com",
- @verifier_email="verifier@example.com">
+ @verifier_email="verifier@example.com",
+ @smtp_safe_check=true>
```
#### Reset configuration
Also you can reset Truemail configuration.
@@ -118,51 +127,78 @@
Example of usage:
1. With default regex pattern
```ruby
-Truemail.configure do |config|
+require 'truemail'
+
+Truemail.configure do |config|
config.verifier_email = 'verifier@example.com'
end
Truemail.validate('email@example.com', with: :regex)
=> #<Truemail::Validator:0x000055590cc9bdb8
- @result=<struct Truemail::Validator::Result success=true, email="email@example.com", domain=nil, mail_servers=[], errors={}, smtp_debug=nil>,
- @validation_type=:regex>
+ @result=
+ #<struct Truemail::Validator::Result
+ success=true, email="email@example.com",
+ domain=nil,
+ mail_servers=[],
+ errors={},
+ smtp_debug=nil>,
+ @validation_type=:regex>
```
2. With custom regex pattern. You should define your custom regex pattern in a gem configuration before.
```ruby
-Truemail.configure do |config|
+require 'truemail'
+
+Truemail.configure do |config|
config.verifier_email = 'verifier@example.com'
config.config.email_pattern = /regex_pattern/
end
Truemail.validate('email@example.com', with: :regex)
=> #<Truemail::Validator:0x000055590ca8b3e8
-@result=<struct Truemail::Validator::Result success=true, email="email@example.com", domain=nil, mail_servers=[], errors={}, smtp_debug=nil>, @validation_type=:regex>
+ @result=
+ #<struct Truemail::Validator::Result
+ success=true,
+ email="email@example.com",
+ domain=nil,
+ mail_servers=[],
+ errors={},
+ smtp_debug=nil>,
+ @validation_type=:regex>
```
#### MX validation
Validation by MX records is second validation level. It uses Regex validation before launch. When regex validation has completed successfully then runs itself.
Example of usage:
```ruby
-Truemail.configure do |config|
+require 'truemail'
+
+Truemail.configure do |config|
config.verifier_email = 'verifier@example.com'
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=["mx1.example.com", "mx2.example.com"], errors={}, smtp_debug=nil>,
- @validation_type=:mx>
+ @result=
+ #<struct Truemail::Validator::Result
+ success=true,
+ email="email@example.com",
+ domain="example.com",
+ mail_servers=["mx1.example.com", "mx2.example.com"],
+ errors={},
+ smtp_debug=nil>,
+ @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 runs itself.
@@ -171,43 +207,152 @@
[Regex validation] -> [MX validation] -> [SMTP validation]
```
By default, you don't need pass with-parameter to use it. Example of usage is specified below:
+With ```smtp_safe_check = false```
+
```ruby
-Truemail.configure do |config|
+require 'truemail'
+
+Truemail.configure do |config|
config.verifier_email = 'verifier@example.com'
end
Truemail.validate('email@example.com')
# Successful SMTP validation
=> #<Truemail::Validator:0x000055590c4dc118
- @result=<struct Truemail::Validator::Result success=true, email="email@example.com", domain="example.com", mail_servers=["mx1.example.com", "mx2.example.com"], errors={}, smtp_debug=nil>,
- @validation_type=:smtp>
+ @result=
+ #<struct Truemail::Validator::Result
+ success=true,
+ email="email@example.com",
+ domain="example.com",
+ mail_servers=["mx1.example.com", "mx2.example.com"],
+ errors={},
+ smtp_debug=nil>,
+ @validation_type=:smtp>
# SMTP validation failed
-=> #<Truemail::Validator:0x000055590cc88150
- @result=
- #<struct Truemail::Validator::Result
- success=false,
- email="email@example.com",
- domain="example.com",
- mail_servers=["mx1.example.com", "mx2.example.com"],
- errors={:smtp=>"smtp error"},
- smtp_debug=
- [#<struct Truemail::Validate::Smtp::Request
- host="mx1.example.com",
+=> #<Truemail::Validator:0x0000000002d5cee0
+ @result=
+ #<struct Truemail::Validator::Result
+ success=false,
+ email="email@example.com",
+ domain="example.com",
+ mail_servers=["mx1.example.com", "mx2.example.com", "mx3.example.com"],
+ errors={:smtp=>"smtp error"},
+ smtp_debug=
+ [#<Truemail::Validate::Smtp::Request:0x0000000002d49b10
+ @configuration=
+ #<Truemail::Configuration:0x0000000002d49930
+ @connection_timeout=2,
+ @email_pattern=/regex_pattern/,
+ @response_timeout=2,
+ @smtp_safe_check=false,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com">,
+ @email="email@example.com",
+ @host="mx1.example.com",
+ @response=
+ #<struct Truemail::Validate::Smtp::Response
+ port_opened=true,
+ connection=true,
+ helo=
+ #<Net::SMTP::Response:0x0000000002d5aca8
+ @status="250",
+ @string="250 mx1.example.com Hello example.com\n">,
+ mailfrom=
+ #<Net::SMTP::Response:0x0000000002d5a618
+ @status="250",
+ @string="250 OK\n">,
+ rcptto=false,
+ errors={:rcptto=>"550 User not found\n"}>>]>,
+ @validation_type=:smtp>
+```
+
+With ```smtp_safe_check = true```
+
+```ruby
+require 'truemail'
+
+Truemail.configure do |config|
+ config.verifier_email = 'verifier@example.com'
+ config.smtp_safe_check = true
+end
+
+Truemail.validate('email@example.com')
+
+# Successful SMTP validation
+=> #<Truemail::Validator:0x0000000002ca2c70
+ @result=
+ #<struct Truemail::Validator::Result
+ success=true,
+ email="email@example.com",
+ domain="example.com",
+ mail_servers=["mx1.example.com"],
+ errors={},
+ smtp_debug=
+ [#<Truemail::Validate::Smtp::Request:0x0000000002c95d40
+ @configuration=
+ #<Truemail::Configuration:0x0000000002c95b38
+ @connection_timeout=2,
+ @email_pattern=/regex_pattern/,
+ @response_timeout=2,
+ @smtp_safe_check=true,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com">,
+ @email="email@example.com",
+ @host="mx1.example.com",
+ @response=
+ #<struct Truemail::Validate::Smtp::Response
+ port_opened=true,
+ connection=false,
+ helo=
+ #<Net::SMTP::Response:0x0000000002c934c8
+ @status="250",
+ @string="250 mx1.example.com\n">,
+ mailfrom=false,
+ rcptto=nil,
+ errors={:mailfrom=>"554 5.7.1 Client host blocked\n", :connection=>"server dropped connection after response"}>>,]>,
+ @validation_type=:smtp>
+
+# SMTP validation failed
+=> #<Truemail::Validator:0x0000000002d5cee0
+ @result=
+ #<struct Truemail::Validator::Result
+ success=false,
email="email@example.com",
- response=
- #<struct Truemail::Validate::Smtp::Response
- port_opened=true,
- connection=true,
- helo=#<Net::SMTP::Response:0x000055590cc74678 @status="250", @string="250 mx1.example.com\n">,
- mailfrom=#<Net::SMTP::Response:0x000055590cc74308 @status="250", @string="250 2.1.0 <verifier@example.com> ok\n">,
- rcptto=false,
- errors={:rcptto=>"550 5.7.1 No such user!\n"}>>]>,
- @validation_type=:smtp>
+ domain="example.com",
+ mail_servers=["mx1.example.com", "mx2.example.com", "mx3.example.com"],
+ errors={:smtp=>"smtp error"},
+ smtp_debug=
+ [#<Truemail::Validate::Smtp::Request:0x0000000002d49b10
+ @configuration=
+ #<Truemail::Configuration:0x0000000002d49930
+ @connection_timeout=2,
+ @email_pattern=/regex_pattern/,
+ @response_timeout=2,
+ @smtp_safe_check=true,
+ @validation_type_by_domain={},
+ @verifier_domain="example.com",
+ @verifier_email="verifier@example.com">,
+ @email="email@example.com",
+ @host="mx1.example.com",
+ @response=
+ #<struct Truemail::Validate::Smtp::Response
+ port_opened=true,
+ connection=true,
+ helo=
+ #<Net::SMTP::Response:0x0000000002d5aca8
+ @status="250",
+ @string="250 mx1.example.com Hello example.com\n">,
+ mailfrom=#<Net::SMTP::Response:0x0000000002d5a618 @status="250", @string="250 OK\n">,
+ rcptto=false,
+ errors={:rcptto=>"550 User not found\n"}>>]>,
+ @validation_type=:smtp>
```
## ToDo
1. Gem compatibility with Ruby 2.3