README.md
# EmailValidator
[](http://travis-ci.com/K-and-R/email_validator)
[](https://codeclimate.com/github/K-and-R/email_validator)
[](https://codeclimate.com/github/K-and-R/email_validator/coverage)
An email validator for Rails 3+.
Supports RFC-2822-compliant and RFC-5321-compliant email validation using RFC-3696 validation.
Formerly found at: <https://github.com/balexand/email_validator>
## Validation philosophy
The default validation provided by this gem (the `:loose` configuration option)
is extremely loose. It just checks that there's an `@` with something before and
after it without any whitespace. See [this article by David Gilbertson](https://medium.com/hackernoon/the-100-correct-way-to-validate-email-addresses-7c4818f24643)
for an explanation of why.
We understand that many use cases require an increased level of validation. This
is supported by using the `:strict` validation mode. Additionally, the `:rfc`
RFC-compliant mode will consider technically valid emails address as valid which
may not be wanted, such as the valid `user` or `user@somehost` addresses. These
would be valid in `:rfc` mode but not valid in `:loose` or `:strict`.
## Installation
Add to your Gemfile:
```ruby
gem 'email_validator'
```
Run:
```bash
bundle install
```
## Usage
Add the following to your model:
```ruby
validates :my_email_attribute, email: true
```
You may wish to allow domains without a FQDN, like `user@somehost`. While this
is technically a valid address, it is uncommon to consider such address valid.
We will consider them valid by default with the `:loose` checking. Disallowed
by setting `require_fqdn: true` or by enabling `:strict` checking:
```ruby
validates :my_email_attribute, email: {mode: :strict, require_fqdn: true}
```
You can also limit to a single domain (e.g: you have separate `User` and
`AdminUser` models and want to ensure that `AdminUser` emails are on a specific
domain):
```ruby
validates :my_email_attribute, email: {domain: 'example.com'}
```
## Configuration
Default configuration can be overridden by setting options in `config/initializers/email_validator.rb`:
```ruby
if defined?(EmailValidator)
# To completely override the defaults
EmailValidator.default_options = {
allow_nil: false,
domain: nil,
require_fqdn: nil,
mode: :loose
}
# or just a few options
EmailValidator.default_options.merge!({ domain: 'mydomain.com' })
end
```
### Loose mode
This it the default validation mode of this gem. It is intentionally extremely
loose (see the [Validation Philosophy section](#validation_philosophy) above. It
just checks that there's an `@` with something before and after it without any
whitespace.
### Strict mode
Enabling `:strict` checking will check for a "normal" email format that would
be expected in most common everyday usage. Strict mode basically checks for a
properly sized and formatted mailbox label, a single "@" symbol, and a properly
sized and formatted FQDN. Enabling `:strict` mode will also enable `:require_fqdn`
configuration option.
Strict mode can be enabled globally by requiring `email_validator/strict` in
your `Gemfile`, by setting the option in `config/initializers/email_validator.rb`,
or by specifying the option in a specific `validates` call.
* `Gemfile`:
```ruby
gem 'email_validator', require: 'email_validator/strict'
```
* `config/initializers/email_validator.rb`:
```ruby
if defined?(EmailValidator)
EmailValidator.default_options[:mode] = :strict
end
```
* `validates` call:
```ruby
validates :my_email_attribute, email: {mode: :strict}
```
### RFC mode
In order to have RFC-compliant validation (according to [http://www.remote.org/jochen/mail/info/chars.html](https://web.archive.org/web/20150508102948/http://www.remote.org/jochen/mail/info/chars.html)),
enable `:rfc` mode.
You can do this globally by requiring `email_validator/rfc` in your `Gemfile`,
by setting the options in `config/initializers/email_validator.rb`, or you can do
this in a specific `validates` call.
* `Gemfile`:
```ruby
gem 'email_validator', require: 'email_validator/rfc'
```
* `config/initializers/email_validator.rb`:
```ruby
if defined?(EmailValidator)
EmailValidator.default_options[:mode] = :rfc
end
```
* `validates` call:
```ruby
validates :my_email_attribute, email: {mode: :rfc}
```
## Validation outside a model
If you need to validate an email outside a model, you can get the regexp:
### Loose/default mode
```ruby
EmailValidator.valid?('narf@example.com') # boolean
```
### Requiring a FQDN
```ruby
EmailValidator.valid?('narf@somehost') # boolean false
EmailValidator.invalid?('narf@somehost', require_fqdn: false) # boolean true
```
_NB: Enabling strict mode (`mode: :strict`) enables `require_fqdn`
(`require_fqdn: true`), overridding any `require_fqdn: false` while
`mode: :strict` is set._
### Requiring a specific domain
```ruby
EmailValidator.valid?('narf@example.com', domain: 'foo.com') # boolean false
EmailValidator.invalid?('narf@example.com', domain: 'foo.com') # boolean true
```
### Strict mode
```ruby
EmailValidator.regexp(mode: :strict) # returns the regex
EmailValidator.valid?('narf@example.com', mode: :strict) # boolean
```
### RFC mode
```ruby
EmailValidator.regexp(mode: :rfc) # returns the regex
EmailValidator.valid?('narf@example.com', mode: :rfc) # boolean
```
## Thread safety
This gem is thread safe, with one caveat: `EmailValidator.default_options` must
be configured before use in a multi-threaded environment. If you configure
`default_options` in a Rails initializer file, then you're good to go since
initializers are run before worker threads are spawned.
## Alternative gems
Do you prefer a different email validation gem? If so, open an issue with a brief
explanation of how it differs from this gem. I'll add a link to it in this README.
* [`email_address`](https://github.com/afair/email_address) (<https://github.com/K-and-R/email_validator/issues/58>)
* [`email_verifier`](https://github.com/kamilc/email_verifier) (<https://github.com/K-and-R/email_validator/issues/65>)
## Maintainers
All thanks is given to [Brian Alexander (balexand)](https://github.com/balexand)
for is initial work on this gem.
Currently maintained by:
* Karl Wilbur (<https://github.com/karlwilbur>)
* K&R Software (<https://github.com/K-and-R>)