Usage: 

  class ApplicationMailer < ActionMailer::Base
    # Set up properties
    # Properties can also be specified via accessor methods
    # (i.e. self.subject = "foo") and instance variables (@subject = "foo").
    def signup_notification(recipient)
      recipients recipient.email_address_with_name
      subject    "New account information"
      body       { "account" => recipient }
      from       "system@example.com"
    end

    # explicitly specify multipart messages
    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

    # 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

    # implicitly multipart messages
    def signup_notification(recipient)
      recipients      recipient.email_address_with_name
      subject         "New account information"
      from            "system@example.com"
      body(:account => "recipient")

      # 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
      # a 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.
    end
  end

  # After this, post_notification will look for "templates/application_mailer/post_notification.rhtml"
  ApplicationMailer.template_root = "templates"

  ApplicationMailer.create_comment_notification(david, hello_world)  # => a tmail object
  ApplicationMailer.deliver_comment_notification(david, hello_world) # sends the email

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.
Methods
Included Modules
Attributes
[R] mail The mail object instance referenced by this mailer.
Public Class methods
deliver(mail)

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)

[ show source ]

     # File lib/action_mailer/base.rb, line 257
257:       def deliver(mail)
258:         new.deliver!(mail)
259:       end
receive(raw_email)

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

[ show source ]

     # File lib/action_mailer/base.rb, line 244
244:       def receive(raw_email)
245:         logger.info "Received mail:\n #{raw_email}" unless logger.nil?
246:         mail = TMail::Mail.parse(raw_email)
247:         mail.base64_decode
248:         new.receive(mail)
249:       end
Public Instance methods
deliver!(mail = @mail)

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.

[ show source ]

     # File lib/action_mailer/base.rb, line 328
328:     def deliver!(mail = @mail)
329:       raise "no mail object available for delivery!" unless mail
330:       logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil?
331: 
332:       begin
333:         send("perform_delivery_#{delivery_method}", mail) if perform_deliveries
334:       rescue Object => e
335:         raise e if raise_delivery_errors
336:       end
337: 
338:       return mail
339:     end
Private Instance methods
create_mail()

[ show source ]

     # File lib/action_mailer/base.rb, line 403
403:       def create_mail
404:         m = TMail::Mail.new
405: 
406:         m.subject, = quote_any_if_necessary(charset, subject)
407:         m.to, m.from = quote_any_address_if_necessary(charset, recipients, from)
408:         m.bcc = quote_address_if_necessary(bcc, charset) unless bcc.nil?
409:         m.cc  = quote_address_if_necessary(cc, charset) unless cc.nil?
410: 
411:         m.mime_version = mime_version unless mime_version.nil?
412:         m.date = sent_on.to_time rescue sent_on if sent_on
413:         headers.each { |k, v| m[k] = v }
414: 
415:         real_content_type, ctype_attrs = parse_content_type
416: 
417:         if @parts.empty?
418:           m.set_content_type(real_content_type, nil, ctype_attrs)
419:           m.body = Utils.normalize_new_lines(body)
420:         else
421:           if String === body
422:             part = TMail::Mail.new
423:             part.body = Utils.normalize_new_lines(body)
424:             part.set_content_type(real_content_type, nil, ctype_attrs)
425:             part.set_content_disposition "inline"
426:             m.parts << part
427:           end
428: 
429:           @parts.each do |p|
430:             part = (TMail::Mail === p ? p : p.to_mail(self))
431:             m.parts << part
432:           end
433:           
434:           if real_content_type =~ /multipart/
435:             ctype_attrs.delete "charset"
436:             m.set_content_type(real_content_type, nil, ctype_attrs)
437:           end
438:         end
439: 
440:         @mail = m
441:       end
initialize_defaults(method_name)

Set up the default values for the various instance variables of this mailer. Subclasses may override this method to provide different defaults.

[ show source ]

     # File lib/action_mailer/base.rb, line 345
345:       def initialize_defaults(method_name)
346:         @charset ||= @@default_charset.dup
347:         @content_type ||= @@default_content_type.dup
348:         @implicit_parts_order ||= @@default_implicit_parts_order.dup
349:         @template ||= method_name
350:         @mailer_name ||= Inflector.underscore(self.class.name)
351:         @parts ||= []
352:         @headers ||= {}
353:         @body ||= {}
354:         @mime_version = @@default_mime_version.dup if @@default_mime_version
355:       end
initialize_template_class(assigns)

[ show source ]

     # File lib/action_mailer/base.rb, line 370
370:       def initialize_template_class(assigns)
371:         ActionView::Base.new(template_path, assigns, self)
372:       end
perform_delivery_sendmail(mail)

[ show source ]

     # File lib/action_mailer/base.rb, line 453
453:       def perform_delivery_sendmail(mail)
454:         IO.popen("/usr/sbin/sendmail -i -t","w+") do |sm|
455:           sm.print(mail.encoded.gsub(/\r/, ''))
456:           sm.flush
457:         end
458:       end
perform_delivery_smtp(mail)

[ show source ]

     # File lib/action_mailer/base.rb, line 443
443:       def perform_delivery_smtp(mail)
444:         destinations = mail.destinations
445:         mail.ready_to_send
446: 
447:         Net::SMTP.start(server_settings[:address], server_settings[:port], server_settings[:domain], 
448:             server_settings[:user_name], server_settings[:password], server_settings[:authentication]) do |smtp|
449:           smtp.sendmail(mail.encoded, mail.from, destinations)
450:         end
451:       end
perform_delivery_test(mail)

[ show source ]

     # File lib/action_mailer/base.rb, line 460
460:       def perform_delivery_test(mail)
461:         deliveries << mail
462:       end
render(opts)

[ show source ]

     # File lib/action_mailer/base.rb, line 361
361:       def render(opts)
362:         body = opts.delete(:body)
363:         initialize_template_class(body).render(opts)
364:       end
render_message(method_name, body)

[ show source ]

     # File lib/action_mailer/base.rb, line 357
357:       def render_message(method_name, body)
358:         render :file => method_name, :body => body
359:       end
sort_parts(parts, order = [])

[ show source ]

     # File lib/action_mailer/base.rb, line 374
374:       def sort_parts(parts, order = [])
375:         order = order.collect { |s| s.downcase }
376: 
377:         parts = parts.sort do |a, b|
378:           a_ct = a.content_type.downcase
379:           b_ct = b.content_type.downcase
380: 
381:           a_in = order.include? a_ct
382:           b_in = order.include? b_ct
383: 
384:           s = case
385:           when a_in && b_in
386:             order.index(a_ct) <=> order.index(b_ct)
387:           when a_in
388:             -1
389:           when b_in
390:             1
391:           else
392:             a_ct <=> b_ct
393:           end
394: 
395:           # reverse the ordering because parts that come last are displayed
396:           # first in mail clients
397:           (s * -1)
398:         end
399: 
400:         parts
401:       end
template_path()

[ show source ]

     # File lib/action_mailer/base.rb, line 366
366:       def template_path
367:         "#{template_root}/#{mailer_name}"
368:       end