You define each different mail that you want to send in a mailer class through what are called mailer actions. A mailer action is just an instance method defined in the mailer class. The body of the mailer action is where you set up instance variables that will be passed to the view template for rendering, add attachments to the email, and set up the headers for the mail message.

Rails provides a generator for creating new mailers. The generator is passed the mailer name in underscored or camel case format followed by zero or more actions:

The generator creates the following files:

Let's generate a new mailer class named OrderMailer with a single action confirmation:

$ rails generate mailer OrderMailer confirmation
      create  app/mailers/order_mailer.rb
      invoke  erb
      create    app/views/order_mailer
      create    app/views/order_mailer/confirmation.text.erb
      invoke  test_unit
      create    test/functional/order_mailer_test.rb

Now let's open up app/mailers/order_mailer.rb and take a look at the mailer that was generated for us:

class OrderMailer < ActionMailer::Base
  default :from => "from@example.com"

  # Subject can be set in your I18n file at config/locales/en.yml
  # with the following lookup:
  #
  #   en.actionmailer.order_mailer.confirmation.subject
  #
  def confirmation
    @greeting = "Hi"

    mail :to => "to@example.org"
  end
end

Mailers are a subclass of ActionMailer::Base, which itself is a subclass of AbstractController::Base. Mailers and controllers both have the same superclass so that they are both act consistently with one another when rendering view templates and utilizing view helpers.

This mailer has a single action, confirmation. Mailer actions are instance methods on mailer classes, just as controller actions are instance methods on controller classes. Any instance variables set within the mailer action will be available in the view template for rendering. This works the in same way that you're used to with Action Controller. In this case, the @greeting instance variable will be passed to the view template, confirmation.text.erb, when it is rendered. Just like controllers, a mailer action will by default render a template with the same name as the mailer action being executed.

At the end of the confirmation mailer action the mail method is called. The mail method renders any view templates and create an instance of a Mail::Message object that is ready for delivery. The mail method takes a hash of email headers, which will be set on the resulting Mail::Message object.

Here’s a list of commonly used options to set email headers:

As can be seen from the example above, you can also set a default hash of mail headers with the class method default. In the example, the :from key in the mail headers hash will default to from@example.org in each mailer action, unless explicitly overridden. You can set a default for any mail header except for date.

Let's modify the generated mailer, app/mailers/order_mailer.rb, to be suitable for sending the confirmation email for simple PDF sales:

class OrderMailer < ActionMailer::Base
  default :from => 'order-confirm@example.com'
  
  def confirmation(order)
    @order = order
    mail(:to => order.email, :subject => 'Your PDF purchase')
  end
end

As you can see, unlike controller actions, mailer actions can take arguments. In this case the mailer action takes an order and passes it to the view template for rendering. We'll see more how this works later in the chapter.

You can render the body of the email by rendering a view template, or by rendering an in-line ERB fragment or text in the mailer action. View templates can be rendered using any template handler registered with Rails such as ERB, Builder, or even a custom handler such as HAML. For more information on template handlers see ???.

Thank you for your purchase of <%= number_to_currency(@order.total) %>.
Your PDF will be delivered to <%= @order.email %>.

class OrderMailer < ActionMailer::Base
  default :from => 'order-confirm@example.com'
  
  def confirmation(order)
    @order = order
    mail(:to => order.email, :subject => 'Your PDF purchase') do |format|
      format.text
    end
  end
end

class OrderMailer < ActionMailer::Base
  default :from => 'order-confirm@example.com'
  
  def confirmation(order)
    mail(:to => order.email, :subject => 'Your PDF purchase') do |format|
      format.text { render :text => "Thank you for your order!" }
    end
  end
end

In order to send an email you first have to create an instance of the class Mail::Message that encapsulates your message. This is done by calling a class method on the mailer with the same name as the mailer action you want to call. So, to create a mail object for the confirmation mailer action of the OrderMailer, you'd call the class method OrderMailer.confirmation. When you call the class method, which is generated dynamically for each action in a mailer, Action Mailer creates an instance of your mailer class, calls the mailer action with any provided arguments, and returns a Mail::Message object representing the message.

In order for our OrderMailer example to work with the we're going to need a simple Order class. Create the file app/models/order.rb and add this simple one liner that allows us to create simple orders with an email address and a total:

Order = Struct.new(:email, :total)

We included email and total attributes on the Order class, as those are the attributes we're displaying in the confirmation.text.erb view template we defined previously. Now we can use the mailer to create a mail instance for us and take a look at some of its properties. You can use the Rails console to try out the following code:

order = Order.new("cody@example.com", 19.95)
mail = OrderMailer.confirmation(order)

mail.to      # => ["cody@example.com"]
mail.from    # => ["order-confirm@example.com"]
mail.subject # => "Your PDF purchase"

Mail::Message objects know how to deliver themselves, so to actually deliver the message you call the deliver instance method on the mail object:

mail.deliver

We'll take a look at how to configure the delivery method later on in this section. You can view the encoded message, which is what is delivered to the MTA, of the message by calling the encoded method on the mail object:

mail.encoded

Here is what the output of the call to encoded looks like for the example on my system:

Date: Sun, 18 Sep 2011 01:21:55 -0400
From: order-confirm@example.com
To: cody@example.com
Message-ID: <4e757ff37c95d_e5c48582c1a483471@Sequoia.local.mail>
Subject: Your PDF purchase
Mime-Version: 1.0
Content-Type: text/plain;
 charset=UTF-8
Content-Transfer-Encoding: 7bit

Thank you for your purchase of $19.95.
Your PDF will be delivered to cody@example.com.

Action Mailer also includes support for generating URIs using helpers that use url_for and named routes in mailers and views. See the section called “Named Routes” for complete coverage of named routes.

You can use view helpers that utilize url_for and named routes just as you would in your controller views. Here we render a URI using url_for and a hash of routing options:

Your account has been suspended.
Log in at: <%= url_for(:controller => 'accounts',
                       :action     => 'show',
                       :id         => @account %>.

One thing to note is that if you're using a hash of routing options you must always pass in the :controller option, as the mailer doesn't know what the current controller is for a request.

This next example uses a named route instead of a hash of routing options to generate the URI:

Your account has been suspended.
Log in at: <%= account_url(@account) %>.

Everything works as you'd expect if you're generating the email during the normal Rails request / response lifecycle. When generating URIs during a normal request, Rails uses the request object to determine what the host portion of the generated URI will be. However, without a request object, Rails doesn't know what to use as the host of generated URIs and will raise an exception.

This means that to generate URIs in mail messages outside of the normal request / response lifecycle, such as in a background job or from the Rails console, you need to provide the :host option so that the URI can be correctly generated. So, our example for a hash of routing options changes to:

Your account has been suspended.
Log in at: <%= url_for(:controller => 'accounts',
                       :action     => 'show',
                       :id         => @account,
                       :host       => 'example.com') %>.

And the named route example changes to:

Your account has been suspended.
Log in at: <%= account_url(@account, :host => 'example.com') %>.

This works, but as you can tell already, will quickly get tedious. Instead of passing in the :host option to every url_for or named route call you can instead set a default :host for all of your mailers. You can do this by setting the ActionMailer::Base.default_url_options accessor to a hash of default URI options:

ActionMailer::Base.default_url_options[:host] = 'example.com'

Or you can set the config.action_mailer.default_url_options configuration setting in your applications environment configuration:

config.action_mailer.default_url_options = { :host => 'example.com' }

See the section called “Action Mailer Configuration” for more about configuring Action Mailer in your Rails application.

Sending email in HTML format allows for a much richer experience than simple plain text email. With HTML email you can style the email content to match your corporate look and feel. Most email clients today support rendering HTML email messages. Action Mailer makes sending very rich HTML email messages extremely simple. To send the confirmation email from Example 11.1, “A Simple Order Mailer” in HTML format, all you need to do is rename the view template from confirmation.text.erb to confirmation.html.erb and place HTML content in the view. Action Mailer will automatically change the content type of the email to text/html for you.

However, sending only HTML content in an email can be problematic when the recipient, such as a cellphone, can't render it. It is also impossible to know what type of device will be receiving the email you send. The solution to this problem is the multipart/alternative MIME type. Setting the content type of an email to multipart/alternative indicates that the body of the email contains the message in multiple alternative formats. This allows you to send a single email with the body in both plain-text and HTML, and instructs the recipient device to display the message in the format that it supports the best.

With Action Mailer all you have to do to take advantage of the multipart/alternative MIME type is create a different view template for each alternative representation of the email body. So, to create a mailer action that creates gracefully degrading HTML email with both the text/plain and text/html content in the body we'd create the following two view templates: app/views/order_mailer/confirmation.text.erb and app/views/order_mailer/confirmation.html.erb.

Action Mailer automatically detects that there are alternative representations of the email body and handles everything for you. This means that you don't even need to modify the code in your mailer action to make this work. Each alternate representation of the email body will be included in the email, allowing the recipient device to render the most appropriate format. However, if you want to be explicit you can declare that you're supporting multiple formats in your mailer action:

class OrderMailer < ActionMailer::Base
  default :from => 'order-confirm@example.com'
  
  def confirmation(order)
    @order = order
    mail(:to => order.email, :subject => 'Your PDF purchase') do |format|
      format.text
      format.html
    end
  end
end

Adding attachments to email messages couldn't be easier with Action Mailer. All you have to do to add attachments to an email message is to add content to the hash-like attachments accessor available within mailer actions. You set a key in the attributes hash to either the content of the attachment or a hash of data in the event you need to manually specify any of the attributes of the attachment. Some examples will clarify how this works. Let's add an mp3 file to the order confirmation email we defined earlier:

class OrderMailer < ActionMailer::Base
  default :from => 'order-confirm@example.com'
  
  def confirmation(order)
    @order = order
    
    attachments['sample.mp3'] = File.read(Rails.root + 'files/sample.mp3')
    mail(:to => order.email, :subject => 'Your PDF purchase')
  end
end

As you can see, we just set the sample.mp3 key in the attachments hash to the binary data of the mp3 file we want to send as the attachment. The mail library uses the file name of the attachment you set to automatically set the Content-Type, Content-Disposition, and Content-Transfer-Encoding of the attachment for you. It will also automatically Base64 encode the attachment's data. If you need to specify any of the properties of the attachment manually then you can set the attachment to a hash of the attachment's attributes and content:

class OrderMailer < ActionMailer::Base
  default :from => 'order-confirm@example.com'
  
  def confirmation(order)
    @order = order
    attachments['sample.mp3'] = {
      :mime_type => 'audio/mpeg',
      :content => File.read(Rails.root + 'files/sample.mp3')
    }
    mail(:to => order.email, :subject => 'Your PDF purchase')
  end
end

There are no settings for test delivery. However, it is worth noting that email for the test environment’s mail back-end is delivered into the ActionMailer::Base.deliveries class accessor. This allows you to inspect the list of delivered email in test cases. Here’s an example within a typical mailer test:

class CustomerMailerTest < ActionMailer::TestCase
  def test_welcome_email
    customer = customers(:some_customer_in_your_fixtures)
 
    # Send the email and ensure it's been queued
    email = AuthorMailer.welcome_email(customer).deliver
    assert !ActionMailer::Base.deliveries.empty?
 
    # Test the body of the sent email contains what we expect it to
    assert_equal [customer.email], email.to
    assert_equal "Thanks for ordering your thing", email.subject
    assert_match(/You are pretty cool, #{customer.name}/, email.encoded)
  end
end