EmailValidator
¶ ↑
An email validator for Rails 3+.
Supports RFC-2822-compliant and RFC-5321-compliant email validation using RFC-3696 validation.
Formerly found at: 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 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:
gem 'email_validator'
Run:
bundle install
Usage¶ ↑
Add the following to your model:
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:
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):
validates :my_email_attribute, email: {domain: 'example.com'}
Configuration¶ ↑
Default configuration can be overridden by setting options in config/initializers/email_validator.rb
:
if defined?(EmailValidator) # To completly 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 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), 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¶ ↑
EmailValidator.valid?('narf@example.com') # boolean
Requiring a FQDN¶ ↑
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¶ ↑
EmailValidator.valid?('narf@example.com', domain: 'foo.com') # boolean false EmailValidator.invalid?('narf@example.com', domain: 'foo.com') # boolean true
Strict mode¶ ↑
EmailValidator.regexp(mode: :strict) # returns the regex EmailValidator.valid?('narf@example.com', mode: :strict) # boolean
RFC mode¶ ↑
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
} (github.com/K-and-R/email_validator/issues/58) -
{
email_verifier
} (github.com/K-and-R/email_validator/issues/65)
Maintainers¶ ↑
All thanks is given to Brian Alexander (balexand) for is initial work on this gem.
Currently maintained by:
-
Karl Wilbur (github.com/karlwilbur)
-
K&R Software (github.com/K-and-R)