ActionMailer Cheatsheet

Mailer Model

To use ActionMailer, you need to create a mailer model. Emails are defined by creating methods within the mailer model which are then used to set variables to be used in the mail template, to change options on the mail, or to add attachments.

Mailer model generator

    ruby script/generate mailer NameOfMailer method1 method2 method3

Example mailer model

    class OrderMailer < ActionMailer::Base

        def confirm(order,sent_at = Time.now)
            subject    "Subject line goes here"
            body       :order => order
            recipients ["bill@microsoft.com", "steve@apple.com"]
            from       "david@dizzy.co.uk"
            sent_on    sent_at
        end    
    end

Delivering mail

Once a mailer action and template are defined, you can deliver your message or create and save it for delivery later by calling the mailer class and prefixing your chosen class method with deliver_ or create_

Send mail

    Notifier.deliver_signup_notification(customer)

Create mail

    mail = Notifier.create_signup_notification(customer)
    Notifier.deliver(mail)

You can pass the mailer model any variables you need to use in the generation of the email. In the example above we have passed it a variable named customer which could be an instance of an ActiveRecord Customer model. We can then access our customer's details in the mailer model.

Multipart messages

There are two ways to send multipart email messages, explicity by manually defining each part, and implicitly by letting ActionMailer do the donkey work.

Explicitly

You can explicitly define multipart messages using the part method...

    part "text/plain" do |p|
        p.body = render_message("signup-as-plain", :account => recipient)
        p.transfer_encoding = "base64"
    end

    part :content_type => "text/html", :body => render_message("signup-as-html", :account => recipient)

Implicitly

ActionMailer will automatically detect and use multipart templates, where each template is named after the name of the method, followed by the content type. Each such detected template will be added as a separate part to the message. For example:

    signup_notification.text.plain.erb
    signup_notification.text.html.erb
    signup_notification.text.xml.builder

Each would be rendered and added as a separate part to the message with the corresponding content type. The same body hash is passed to each template.

Views & Templates

Like ActionController, each mailer class has a corresponding view directory in which each method of the class looks for a template with its own name. For example...

Mailer Configuration Methods

    body :order => order, :name => name

    attachment :content_type => "image/jpeg", :body => File.read("an-image.jpg")
      attachment "application/pdf" do |a| 
        a.body = generate_your_pdf_here()
      end

    headers "X-Mail-Count" => 107370

URLs

If your view includes URLs from the application, you need to use url_for in the mailer class method instead of in the view template. You can pass the result to the view via the body method. Unlike controllers from ActionPack, the mailer instance doesn't have any context about the incoming request.

    body :home_page => url_for(:host => "dizzy.co.uk", :controller => "welcome", :action => "index")

ActionMailer::Base Configuration Methods

ActionMailer is configured by acessing configuration methods at the class level, for example, ActionMailer::Base.template_root = "/my/templates". These methods allow you to define the overall settings to be used by your application whenever it invokes ActionMailer. Define these settings in your config/environment.rb file using config.action_mailer.method_name_here. If you require different settings for each of your Rails' environments, define settings separately via config/environments.

Comments