Class: ActionMailer::Base

Inherits:

Object

• Object
• ActionMailer::Base

Includes:

AdvAttrAccessor, PartContainer, Reloadable::Subclasses

Defined in:

lib/action_mailer/base.rb

Overview

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

Mailer Models

To use ActionMailer, 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
    from       "system@example.com"
    subject    "New account information"
    body       "account" => recipient
  end
end

Mailer methods have the following configuration methods available.

• recipients - Takes one or more email addresses. These addresses are where your email will be delivered to. Sets the To: header.

• subject - The subject of your email. Sets the Subject: header.

• from - Who the email you are sending is from. Sets the From: header.

• cc - Takes one or more email addresses. These addresses will receive a carbon copy of your email. Sets the Cc: header.

• bcc - Takes one or more email address. These addresses will receive a blind carbon copy of your email. Sets the Bcc header.

• sent_on - The date on which the message was sent. If not set, the header wil be set by the delivery agent.

• content_type - Specify the content type of the message. Defaults to text/plain.

• headers - Specify additional headers to be set for the message, e.g. headers 'X-Mail-Count' => 107370.

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 ActionController, 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 .rhtml 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.rhtml 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.

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 .rhtml 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"
    body       "account" => recipient
    from       "system@example.com"
    content_type "text/html"   #    Here's where the magic happens
  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"

    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 ActionMailer 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:

• signup_notification.text.plain.rhtml

• signup_notification.text.html.rhtml

• signup_notification.text.xml.rxml

• signup_notification.text.x-yaml.rhtml

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.

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

Configuration options

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

• template_root - template root determines the base from which template references will be made.

• logger - the logger is used for generating information on the mailing run if available. Can be set to nil for no logging. Compatible with both Ruby’s own Logger and Log4r loggers.

• server_settings - Allows detailed configuration of the server:

  • :address Allows you to use a remote mail server. Just change it from its default “localhost” setting.

  • :port On the off chance that your mail server doesn’t run on port 25, you can change it.

  • :domain If you need to specify a HELO domain, you can do it here.

  • :user_name If your mail server requires authentication, set the username in this setting.

  • :password If your mail server requires authentication, set the password in this setting.

  • :authentication If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of :plain, :login, :cram_md5

• raise_delivery_errors - whether or not errors should be raised if the email fails to be delivered.

• delivery_method - Defines a delivery method. Possible values are :smtp (default), :sendmail, and :test. Sendmail is assumed to be present at “/usr/sbin/sendmail”.

• perform_deliveries - Determines whether deliver_* methods are actually carried out. By default they are, but this can be turned off to help functional testing.

• deliveries - Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful for unit and functional testing.

• default_charset - The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also pick a different charset from inside a method with @charset.

• default_content_type - The default content type used for the main part of the message. Defaults to “text/plain”. You can also pick a different content type from inside a method with @content_type.

• default_mime_version - The default mime version used for the message. Defaults to nil. You can also pick a different value from inside a method with @mime_version. When multipart messages are in use, @mime_version will be set to “1.0” if it is not set inside a method.

• default_implicit_parts_order - When a message is built implicitly (i.e. multiple parts are assembled from templates which specify the content type in their filenames) this variable controls how the parts are ordered. Defaults to [“text/html”, “text/enriched”, “text/plain”]. Items that appear first in the array have higher priority in the mail client and appear last in the mime encoded message. You can also pick a different order from inside a method with @implicit_parts_order.

Constant Summary

@@server_settings =

{ 
  :address        => "localhost", 
  :port           => 25, 
  :domain         => 'localhost.localdomain', 
  :user_name      => nil, 
  :password       => nil, 
  :authentication => nil
}

@@raise_delivery_errors =

true

@@delivery_method =

:smtp

@@perform_deliveries =

true

@@deliveries =

[]

@@default_charset =

"utf-8"

@@default_content_type =

"text/plain"

@@default_mime_version =

nil

@@default_implicit_parts_order =

[ "text/html", "text/enriched", "text/plain" ]

Instance Attribute Summary

• #mail ⇒ Object readonly

  The mail object instance referenced by this mailer.

Attributes included from PartContainer

#parts

Class Method Summary

• .deliver(mail) ⇒ Object

  Deliver the given mail object directly.

• .method_missing(method_symbol, *parameters) ⇒ Object

  :nodoc:.

• .receive(raw_email) ⇒ Object

  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.

Instance Method Summary

• #create!(method_name, *parameters) ⇒ Object

  Initialize the mailer via the given method_name.

• #deliver!(mail = @mail) ⇒ Object

  Delivers a TMail::Mail object.

• #initialize(method_name = nil, *parameters) ⇒ Base constructor

  Instantiate a new mailer object.

Methods included from AdvAttrAccessor

append_features

Methods included from PartContainer

#attachment, #part

Constructor Details

#initialize(method_name = nil, *parameters) ⇒ Base

Instantiate a new mailer object. If method_name is not nil, the mailer will be initialized according to the named method. If not, the mailer will remain uninitialized (useful when you only need to invoke the “receive” method, for instance).

# File 'lib/action_mailer/base.rb', line 330

def initialize(method_name=nil, *parameters) #:nodoc:
  create!(method_name, *parameters) if method_name 
end

Instance Attribute Details

#mail ⇒ Object (readonly)

The mail object instance referenced by this mailer.

# File 'lib/action_mailer/base.rb', line 285

def mail
  @mail
end

Class Method Details

.deliver(mail) ⇒ Object

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 321

def deliver(mail)
  new.deliver!(mail)
end

.method_missing(method_symbol, *parameters) ⇒ Object

:nodoc:

# File 'lib/action_mailer/base.rb', line 288

def method_missing(method_symbol, *parameters)#:nodoc:
  case method_symbol.id2name
    when /^create_([_a-z]\w*)/  then new($1, *parameters).mail
    when /^deliver_([_a-z]\w*)/ then new($1, *parameters).deliver!
    when "new" then nil
    else super
  end
end

.receive(raw_email) ⇒ Object

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 308

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

Instance Method Details

#create!(method_name, *parameters) ⇒ Object

Initialize the mailer via the given method_name. The body will be rendered and a new TMail::Mail object created.

# File 'lib/action_mailer/base.rb', line 336

def create!(method_name, *parameters) #:nodoc:
  initialize_defaults(method_name)
  send(method_name, *parameters)

  # If an explicit, textual body has not been set, we check assumptions.
  unless String === @body
    # First, we look to see if there are any likely templates that match,
    # which include the content-type in their file name (i.e.,
    # "the_template_file.text.html.rhtml", etc.). Only do this if parts
    # have not already been specified manually.
    if @parts.empty?
      templates = Dir.glob("#{template_path}/#{@template}.*")
      templates.each do |path|
        # TODO: don't hardcode rhtml|rxml
        basename = File.basename(path)
        next unless md = /^([^\.]+)\.([^\.]+\.[^\+]+)\.(rhtml|rxml)$/.match(basename)
        template_name = basename
        content_type = md.captures[1].gsub('.', '/')
        @parts << Part.new(:content_type => content_type,
          :disposition => "inline", :charset => charset,
          :body => render_message(template_name, @body))
      end
      unless @parts.empty?
        @content_type = "multipart/alternative"
        @parts = sort_parts(@parts, @implicit_parts_order)
      end
    end

    # Then, if there were such templates, we check to see if we ought to
    # also render a "normal" template (without the content type). If a
    # normal template exists (or if there were no implicit parts) we render
    # it.
    template_exists = @parts.empty?
    template_exists ||= Dir.glob("#{template_path}/#{@template}.*").any? { |i| File.basename(i).split(".").length == 2 }
    @body = render_message(@template, @body) if template_exists

    # Finally, if there are other message parts and a textual body exists,
    # we shift it onto the front of the parts and set the body to nil (so
    # that create_mail doesn't try to render it in addition to the parts).
    if !@parts.empty? && String === @body
      @parts.unshift Part.new(:charset => charset, :body => @body)
      @body = nil
    end
  end

  # If this is a multipart e-mail add the mime_version if it is not
  # already set.
  @mime_version ||= "1.0" if !@parts.empty?

  # build the mail object itself
  @mail = create_mail
end

#deliver!(mail = @mail) ⇒ Object

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 392

def deliver!(mail = @mail)
  raise "no mail object available for delivery!" unless mail
  logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil?

  begin
    send("perform_delivery_#{delivery_method}", mail) if perform_deliveries
  rescue Object => e
    raise e if raise_delivery_errors
  end

  return mail
end