Action Mailer – Easy email delivery and testing
Action Mailer is a framework for designing email service layers. These layers are used to consolidate code for sending out forgotten passwords, welcome wishes on signup, invoices for billing, and any other use case that requires a written notification to either a person or another system.
Action Mailer is in essence a wrapper around Action Controller and the Mail gem. It provides a way to make emails using templates in the same way that Action Controller renders views using templates.
Additionally, an Action Mailer class can be used to process incoming email, such as allowing a blog to accept new posts from an email (which could even have been sent from a phone).
Sending emails
The framework works by initializing any instance variables you want to be
available in the email template, followed by a call to mail
to
deliver the email.
This can be as simple as:
class Notifier < ActionMailer::Base
default from: 'system@loudthinking.com'
def welcome(recipient)
@recipient = recipient
mail(to: recipient,
subject: "[Signed up] Welcome #{recipient}")
end
end
The body of the email is created by using an Action View template (regular ERB) that has the instance variables that are declared in the mailer action.
So the corresponding body template for the method above could look like this:
Hello there,
Mr. <%= @recipient %>
Thank you for signing up!
If the recipient was given as “david@loudthinking.com”, the email generated would look like this:
Date: Mon, 25 Jan 2010 22:48:09 +1100
From: system@loudthinking.com
To: david@loudthinking.com
Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail>
Subject: [Signed up] Welcome david@loudthinking.com
Mime-Version: 1.0
Content-Type: text/plain;
charset="US-ASCII";
Content-Transfer-Encoding: 7bit
Hello there,
Mr. david@loudthinking.com
Thank you for signing up!
In order to send mails, you simply call the method and then call
deliver
on the return value.
Calling the method returns a Mail Message object:
message = Notifier.welcome("david@loudthinking.com") # => Returns a Mail::Message object
message.deliver # => delivers the email
Or you can just chain the methods together like:
Notifier.welcome("david@loudthinking.com").deliver # Creates the email and sends it immediately
Setting defaults
It is possible to set default values that will be used in every method in
your Action Mailer class. To implement this functionality, you just call
the public class method default
which you get for free from
ActionMailer::Base
. This method accepts a Hash as the parameter. You can use any
of the headers email messages have, like :from
as the key. You
can also pass in a string as the key, like “Content-Type”, but Action
Mailer does this out of the box for you, so you won't need to worry
about that. Finally, it is also possible to pass in a Proc that will get
evaluated when it is needed.
Note that every value you set with this method will get overwritten if you use the same key in your mailer method.
Example:
class AuthenticationMailer < ActionMailer::Base
default from: "awesome@application.com", subject: Proc.new { "E-mail was generated at #{Time.now}" }
.....
end
Receiving emails
To receive emails, you need to implement a public instance method called
receive
that takes an email object as its single parameter.
The Action Mailer framework has a corresponding class method, which is also
called receive
, that accepts a raw, unprocessed email as a
string, which it then turns into the email object and calls the receive
instance method.
Example:
class Mailman < ActionMailer::Base
def receive(email)
page = Page.find_by(address: email.to.first)
page.emails.create(
subject: email.subject, body: email.body
)
if email.has_attachments?
email.attachments.each do |attachment|
page.attachments.create({
file: attachment, description: email.subject
})
end
end
end
end
This Mailman can be the target for Postfix or other MTAs. In Rails, you would use the runner in the trivial case like this:
rails runner 'Mailman.receive(STDIN.read)'
However, invoking Rails in the runner for each mail to be received is very resource intensive. A single instance of Rails should be run within a daemon, if it is going to process more than just a limited amount of email.
Configuration
The Base class has the full list of configuration options. Here's an example:
ActionMailer::Base.smtp_settings = {
address: 'smtp.yourserver.com', # default: localhost
port: '25', # default: 25
user_name: 'user',
password: 'pass',
authentication: :plain # :plain, :login or :cram_md5
}
Download and installation
The latest version of Action Mailer can be installed with RubyGems:
% [sudo] gem install actionmailer
Source code can be downloaded as part of the Rails project on GitHub
License
Action Mailer is released under the MIT license:
Support
API documentation is at
Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here: