validates_email_format_of Gem and Rails Plugin

Validate e-mail addresses against RFC 2822 and RFC 3696.

Installation

Installing as a gem:

gem install validates_email_format_of

Or in your Gemfile:

gem 'validates_email_format_of'

Usage

# Rails
# I18n locales are loaded automatically.
class Person < ActiveRecord::Base
  validates_email_format_of :email, :message => 'is not looking good'
  # OR
  validates :email, :email_format => { :message => 'is not looking good' }
end

# Now you can test your model using RSpec:
require "validates_email_format_of/rspec_matcher"
describe Person do
  it { should validate_email_format_of(:email).with_message('is not looking good') }
end

# If you're not using Rails (which really means, if you're not using ActiveModel::Validations)
ValidatesEmailFormatOf::load_i18n_locales # Optional, if you want error messages to be in your language
I18n.locale = :pl # If, for example, you want Polish error messages.
ValidatesEmailFormatOf::validate_email_format("[email protected]") # => nil
ValidatesEmailFormatOf::validate_email_format("invalid_because_there_is_no_at_symbol") # => ["does not appear to be a valid e-mail address"]

Options

:message
   String. A custom error message when the email format is invalid (default is: "does not appear to be a valid e-mail address")
:check_mx
   Boolean. Check domain for a valid MX record (default is false)
: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
  Maximum number of characters allowed in the local part (everything before the '@') (default is 64)
:domain_length
  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)
:with
  Specify a custom Regex as the valid email format.
:on, :if, :unless, :allow_nil, :allow_blank, :strict
   Standard ActiveModel validation options.  These work in the ActiveModel/ActiveRecord/Rails syntax only.
   See http://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html#method-i-validates for details.

Testing

To execute the unit tests run rspec.

Tested in Ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0, 2.1.2, JRuby and REE 1.8.7.

Contributing

If you think we’re letting some rules about valid email formats slip through the cracks, don’t just update the Regex. 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

Credits

Written by Alex Dunae (dunae.ca), 2006-11.

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

Thanks to Francis Hwang (fhwang.net/) 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 (www.riverocktech.com/) for creating the 1.4 update.

Thanks to George Anderson (github.com/george) and ‘history’ (github.com/history) for creating the 1.4.1 update.

Thanks to Isaac Betesh (github.com/betesh) for converting tests to Rspec and refactoring for version 1.6.0.