mail_form

MailForm

Rails 7+

This gem was built on top of ActiveModel to showcase how you can pull in validations, naming and i18n from Rails to your models without the need to implement it all by yourself.

This README refers to the MailForm gem to be used in Rails 7+. For instructions on how to use MailForm in older versions of Rails, please refer to the available branches.

Description

MailForm allows you to send an e-mail straight from a form. For instance, if you want to make a contact form just the following lines are needed (including the e-mail):

class ContactForm )
    }
  end
end

Then you start a console with rails console and type:

>> c = ContactForm.new(name: 'José', email: '[email protected]', message: 'Cool!')
>> c.deliver

Check your inbox and the e-mail will be there, with the sent fields (assuming that you configured your mailer delivery method properly).

MailForm::Base

When you inherit from MailForm::Base, it pulls down a set of stuff from ActiveModel, as ActiveModel::Validation, ActiveModel::Translation and ActiveModel::Naming.

This brings I18n, error messages, validations and attributes handling like in ActiveRecord to MailForm, so MailForm can be used in your controllers and form builders without extra tweaks. This also means that instead of the following:

attribute :email, validate: /\A[^@\s]+@[^@\s]+\z/i

You could actually do this:

attribute :email
validates_format_of :email, with: /\A[^@\s]+@[^@\s]+\z/i

Choose the one which pleases you the most. For more information on the API, please continue reading below.

Playing together ORMs

MailForm plays nice with ORMs as well. You just need to include MailForm::Delivery in your model and declare which attributes should be sent:

class User  true
c.spam?    #=> true  (raises an error in development, to remember you to hide it)
c.deliver  #=> false (just delivers if is not a spam and is valid, raises an error in development)

c = ContactForm.new(email: 'invalid')
c.valid?               #=> false
c.errors.inspect       #=> { name: :blank, email: :invalid }
c.errors.full_messages #=> [ "Name can't be blank", "Email is invalid" ]

c = ContactForm.new(name: 'José', email: '[email protected]')
c.deliver

append(*methods)

MailForm also makes easy to append request information from client to the sent mail. You just have to do:

class ContactForm < MailForm::Base
  append :remote_ip, :user_agent, :session
  # ...
end

And in your controller:

@contact_form = ContactForm.new(params[:contact_form])
@contact_form.request = request

The remote ip, user agent and session will be sent in the e-mail in a request information session. You can give to append any method that the request object responds to.

I18n

I18n in MailForm works like in ActiveRecord, so all models, attributes and messages can be used with localized. Below is an I18n file example file:

mail_form:
  models:
    contact_form: "Your site contact form"
  attributes:
    contact_form:
      email: "E-mail"
      telephone: "Telephone number"
      message: "Sent message"
  request:
    title: "Technical information about the user"
    remote_ip: "IP Address"
    user_agent: "Browser"

Custom e-mail template

To customize the e-mail template that is used create a file called contact.erb in app/views/mail_form. Take a look at lib/mail_form/views/mail_form/contact.erb in this repo to see how the default template works.

Supported Ruby / Rails versions

We intend to maintain support for all Ruby / Rails versions that haven't reached end-of-life.

For more information about specific versions please check Ruby and Rails maintenance policies, and our test matrix.

Bugs and Feedback

If you discover any bug, please use github issues tracker.

License

MIT License. Copyright 2009-2019 Plataformatec. Copyright 2020-CURRENT Rafael França, Carlos Antonio da Silva.