Parent

Included Modules

Class/Module Index [+]

Quicksearch

ActionMailer::Base

Action Mailer allows you to send email from your application using a mailer model and views.

Mailer Models

To use Action Mailer, you need to create a mailer model.

$ script/generate mailer Notifier

The generated model inherits from ActionMailer::Base. Emails are defined by creating methods within the 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.

Examples:

class Notifier < ActionMailer::Base
  def signup_notification(recipient)
    recipients recipient.email_address_with_name
    bcc        ["bcc@example.com", "Order Watcher <watcher@example.com>"]
    from       "system@example.com"
    subject    "New account information"
    body       :account => recipient
  end
end

Mailer methods have the following configuration methods available.

When a headers 'return-path' is specified, that value will be used as the ‘envelope from’ address. Setting this is useful when you want delivery notifications sent to a different address than the one in from.

The body method has special behavior. It takes a hash which generates an instance variable named after each key in the hash containing the value that that key points to.

So, for example, body :account => recipient would result in an instance variable @account with the value of recipient being accessible in the view.

Mailer views

Like Action Controller, each mailer class has a corresponding view directory in which each method of the class looks for a template with its name. To define a template to be used with a mailing, create an .erb file with the same name as the method in your mailer model. For example, in the mailer defined above, the template at app/views/notifier/signup_notification.erb would be used to generate the email.

Variables defined in the model are accessible as instance variables in the view.

Emails by default are sent in plain text, so a sample view for our model example might look like this:

Hi <%= @account.name %>,
Thanks for joining our service! Please check back often.

You can even use Action Pack helpers in these views. For example:

You got a new note!
<%= truncate(note.body, 25) %>

Generating URLs

URLs can be generated in mailer views using url_for or named routes. Unlike controllers from Action Pack, the mailer instance doesn’t have any context about the incoming request, so you’ll need to provide all of the details needed to generate a URL.

When using url_for you’ll need to provide the :host, :controller, and :action:

<%= url_for(:host => "example.com", :controller => "welcome", :action => "greeting") %>

When using named routes you only need to supply the :host:

<%= users_url(:host => "example.com") %>

You will want to avoid using the name_of_route_path form of named routes because it doesn’t make sense to generate relative URLs in email messages.

It is also possible to set a default host that will be used in all mailers by setting the :host option in the ActionMailer::Base.default_url_options hash as follows:

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

This can also be set as a configuration option in config/environment.rb:

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

If you do decide to set a default :host for your mailers you will want to use the :only_path => false option when using url_for. This will ensure that absolute URLs are generated because the url_for view helper will, by default, generate relative URLs when a :host option isn’t explicitly provided.

Sending mail

Once a mailer action and template are defined, you can deliver your message or create it and save it for delivery later:

Notifier.deliver_signup_notification(david) # sends the email
mail = Notifier.create_signup_notification(david)  # => a tmail object
Notifier.deliver(mail)

You never instantiate your mailer class. Rather, your delivery instance methods are automatically wrapped in class methods that start with the word deliver_ followed by the name of the mailer method that you would like to deliver. The signup_notification method defined above is delivered by invoking Notifier.deliver_signup_notification.

HTML email

To send mail as HTML, make sure your view (the .erb file) generates HTML and set the content type to html.

class MyMailer < ActionMailer::Base
  def signup_notification(recipient)
    recipients   recipient.email_address_with_name
    subject      "New account information"
    from         "system@example.com"
    body         :account => recipient
    content_type "text/html"
  end
end

Multipart email

You can explicitly specify multipart messages:

class ApplicationMailer < ActionMailer::Base
  def signup_notification(recipient)
    recipients      recipient.email_address_with_name
    subject         "New account information"
    from            "system@example.com"
    content_type    "multipart/alternative"

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

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

Multipart messages can also be used implicitly because Action Mailer will automatically detect and use multipart templates, where each template is named after the name of the action, followed by the content type. Each such detected template will be added as separate part to the message.

For example, if the following templates existed:

Each would be rendered and added as a separate part to the message, with the corresponding content type. The content type for the entire message is automatically set to multipart/alternative, which indicates that the email contains multiple different representations of the same email body. The same body hash is passed to each template.

Implicit template rendering is not performed if any attachments or parts have been added to the email. This means that you’ll have to manually add each part to the email and set the content type of the email to multipart/alternative.

Attachments

Attachments can be added by using the attachment method.

Example:

class ApplicationMailer < ActionMailer::Base
  # attachments
  def signup_notification(recipient)
    recipients      recipient.email_address_with_name
    subject         "New account information"
    from            "system@example.com"

    attachment :content_type => "image/jpeg",
      :body => File.read("an-image.jpg")

    attachment "application/pdf" do |a|
      a.body = generate_your_pdf_here()
    end
  end
end

Multipart Emails with Attachments

Multipart emails that also have attachments can be created by nesting a “multipart/alternative” part within an email that has its content type set to “multipart/mixed”. This would also need two templates in place within app/views/mailer called “welcome_email.text.html.erb” and “welcome_email.text.plain.erb”

class ApplicationMailer < ActionMailer::Base
  def signup_notification(recipient)
    recipients      recipient.email_address_with_name
    subject         "New account information"
    from            "system@example.com"
    content_type    "multipart/mixed"

    part "multipart/alternative" do |alternative|

      alternative.part "text/html" do |html|
        html.body = render_message("welcome_email.text.html", :message => "<h1>HTML content</h1>")
      end

      alternative.part "text/plain" do |plain|
        plain.body = render_message("welcome_email.text.plain", :message => "text content")
      end

    end

    attachment :content_type => "image/png",
      :body => File.read(File.join(RAILS_ROOT, 'public/images/rails.png'))

    attachment "application/pdf" do |a|
      a.body = File.read('/Users/mikel/Code/mail/spec/fixtures/attachments/test.pdf')
    end
  end
end

Configuration options

These options are specified on the class level, like ActionMailer::Base.template_root = "/my/templates"

Attributes

mailer_name[W]
action_name[R]
default_template_name[R]
mail[R]

The mail object instance referenced by this mailer.

template_name[R]

Public Class Methods

controller_name() click to toggle source

for ActionView compatibility

Alias for: mailer_name
controller_path() click to toggle source
Alias for: mailer_name
deliver(mail) click to toggle source

Deliver the given mail object directly. This can be used to deliver a preconstructed mail object, like:

email = MyMailer.create_some_mail(parameters)
email.set_some_obscure_header "frobnicate"
MyMailer.deliver(email)
# File lib/action_mailer/base.rb, line 461
def deliver(mail)
  new.deliver!(mail)
end
mailer_name() click to toggle source
# File lib/action_mailer/base.rb, line 412
def mailer_name
  @mailer_name ||= name.underscore
end
Also aliased as: controller_name, controller_path
receive(raw_email) click to toggle source

Receives a raw email, parses it into an email object, decodes it, instantiates a new mailer, and passes the email object to the mailer object’s receive method. If you want your mailer to be able to process incoming messages, you’ll need to implement a receive method that accepts the email object as a parameter:

class MyMailer < ActionMailer::Base
  def receive(mail)
    ...
  end
end
# File lib/action_mailer/base.rb, line 448
def receive(raw_email)
  logger.info "Received mail:\n #{raw_email}" unless logger.nil?
  mail = TMail::Mail.parse(raw_email)
  mail.base64_decode
  new.receive(mail)
end
template_root() click to toggle source
# File lib/action_mailer/base.rb, line 465
def template_root
  self.view_paths && self.view_paths.first
end
template_root=(root) click to toggle source
# File lib/action_mailer/base.rb, line 469
def template_root=(root)
  self.view_paths = ActionView::Base.process_view_paths(root)
end

Public Instance Methods

deliver!(mail = @mail) click to toggle source

Delivers a TMail::Mail object. By default, it delivers the cached mail object (from the create! method). If no cached mail object exists, and no alternate has been given as the parameter, this will fail.

# File lib/action_mailer/base.rb, line 548
def deliver!(mail = @mail)
  raise "no mail object available for delivery!" unless mail
  unless logger.nil?
    logger.info  "Sent mail to #{Array(recipients).join(', ')}"
    logger.debug "\n#{mail.encoded}"
  end

  begin
    __send__("perform_delivery_#{delivery_method}", mail) if perform_deliveries
  rescue Exception => e  # Net::SMTP errors or sendmail pipe errors
    raise e if raise_delivery_errors
  end

  return mail
end
mailer_name(value = nil) click to toggle source

Override the mailer name, which defaults to an inflected version of the mailer’s class name. If you want to use a template in a non-standard location, you can use this to specify that location.

# File lib/action_mailer/base.rb, line 393
def mailer_name(value = nil)
  if value
    self.mailer_name = value
  else
    self.class.mailer_name
  end
end
mailer_name=(value) click to toggle source
# File lib/action_mailer/base.rb, line 401
def mailer_name=(value)
  self.class.mailer_name = value
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.