validates_email_format_of

A Ruby gem to validate email addresses against RFC 2822 and RFC 5322, with optional domain name lookups.

Why this email validator?

This gem is the O.G. email validation gem for Rails. It was started back in 2006.

Why use this validator? Instead of trying to validate email addresses with one giant regular expression, this library parses addresses character by character. This lets us handle weird cases like nested comments. Gross, but technically allowed.

In reality, most email validating scripts will get you where you need to go. This library just aims to go all the way.

Installation

Add the gem to your Gemfile with:

gem 'validates_email_format_of'

Usage in a Rails app

class Person < ActiveRecord::Base
  validates :email, :email_format => { :message => "is not looking good" }

  # OR

  validates_email_format_of :email, :message => "is not looking good"
end

You can use the included rspec matcher as well:

require "validates_email_format_of/rspec_matcher"

describe Person do
  it { should validate_email_format_of(:email).with_message("is not looking good") }
end

Usage without Rails

ValidatesEmailFormatOf::validate_email_format("example@mydomain.com") # => nil
ValidatesEmailFormatOf::validate_email_format("invalid@") # => ["does not appear to be a valid email address"]

# Optional, if you want error messages to be in your language
ValidatesEmailFormatOf::load_i18n_locales
I18n.locale = :pl

ValidatesEmailFormatOf::validate_email_format("invalid@") # => ["nieprawidłowy adres email"]

Internationalized Domain Names (IDN) and Punycode

As of v1.8.0, this gem can validate email addresses using internationalized domain names (like test@пример.рф) as well as domains that have already been converted to Punycode code (like test@xn--test@-3weu6azakd.xn--p1ai).

If you would like to forbid internationalized domains, you can pass the idn: false option. Punycode is always accepted.

Options

Option	Type	Description
:message	String	A custom error message when the email format is invalid (default is: "does not appear to be a valid email address")
:check_mx	Boolean	Check domain for a valid MX record (default is false)
:check_mx_timeout	Integer	Timeout in seconds for checking MX records before a ResolvTimeout is raised (default is 3).
:idn	Boolean	Allowed internationalized domain names like test@exämple.com and test@пример.рф. Otherwise only domains that have already been converted to Punycode are supported. (default is true)
:mx_message	String	A custom error message when the domain does not match a valid MX record (default is: "is not routable"). Ignored unless :check_mx option is true.
:local_length	Integer	Maximum number of characters allowed in the local part (everything before the '@') (default is 64)
:domain_length	Integer	Maximum number of characters allowed in the domain part (everything after the '@') (default is 255)
:generate_message	Boolean	Return the I18n key of the error message instead of the error message itself (default is false)

The standard ActiveModel validation options (:on, :if, :unless, :allow_nil, :allow_blank, etc...) all work as well when using the gem as part of a Rails application.

Testing

The gem is tested against Rails 4.2 and onward across a bunch of Ruby versions including jruby. You can see our current Ruby and Rails test matrix here.

To execute the unit tests against all the Rails versions we support run bundle exec appraisal rspec or run against an individual version with bundle exec appraisal rails-6.0 rspec.

Contributing

If you think we're letting some rules about valid email formats slip through the cracks, don't just update the parser. Instead, add a failing test and demonstrate that the described email address should be treated differently. A link to an appropriate RFC is the best way to do this. Then change the gem code to make the test pass.

describe "i_think_this_is_not_a_v@lid_email_addre.ss" do
  # According to http://..., this email address IS NOT valid.
  it { should have_errors_on_email.because("does not appear to be valid") }
end

describe "i_think_this_is_a_v@lid_email_addre.ss" do
  # According to http://..., this email address IS valid.
  it { should_not have_errors_on_email }
end

Yes, our Rspec syntax is that simple!

Homepage

• https://github.com/validates-email-format-of/validates_email_format_of

Credits

Written by Alex Dunae, 2006-24.

Many thanks to the plugin's recent contributors: https://github.com/alexdunae/validates_email_format_of/contributors

Thanks to Francis Hwang at Diversion Media for creating the 1.1 update.

Thanks to Travis Sinnott for creating the 1.3 update.

Thanks to Denis Ahearn at Riverock Technologies for creating the 1.4 update.

Thanks to George Anderson and 'history' for creating the 1.4.1 update.

Thanks to Isaac Betesh for converting tests to Rspec and refactoring for version 1.6.0.