mail

The main method that creates the message and renders the email templates. There are two ways to call this method, with a block, or without a block.

Both methods accept a headers hash. This hash allows you to specify the most used headers in an email message, these are:

• :subject - The subject of the message, if this is omitted, Action Mailer will ask the Rails I18n class for a translated :subject in the scope of [mailer_scope, action_name] or if this is missing, will translate the humanized version of the action_name

• :to - Who the message is destined for, can be a string of addresses, or an array of addresses.

• :from - Who the message is from

• :cc - Who you would like to Carbon-Copy on this email, can be a string of addresses, or an array of addresses.

• :bcc - Who you would like to Blind-Carbon-Copy on this email, can be a string of addresses, or an array of addresses.

• :reply_to - Who to set the Reply-To header of the email to.

• :date - The date to say the email was sent on.

You can set default values for any of the above headers (except :date) by using the ::default class method:

class Notifier < ActionMailer::Base
  default from: 'no-reply@test.lindsaar.net',
          bcc: 'email_logger@test.lindsaar.net',
          reply_to: 'bounces@test.lindsaar.net'
end

If you need other headers not listed above, you can either pass them in as part of the headers hash or use the headers['name'] = value method.

When a :return_path is specified as header, that value will be used as the ‘envelope from’ address for the Mail message. Setting this is useful when you want delivery notifications sent to a different address than the one in :from. Mail will actually use the :return_path in preference to the :sender in preference to the :from field for the ‘envelope from’ value.

If you do not pass a block to the mail method, it will find all templates in the view paths using by default the mailer name and the method name that it is being called from, it will then create parts for each of these templates intelligently, making educated guesses on correct content type and sequence, and return a fully prepared Mail::Message ready to call :deliver on to send.

For example:

class Notifier < ActionMailer::Base
  default from: 'no-reply@test.lindsaar.net'

  def welcome
    mail(to: 'mikel@test.lindsaar.net')
  end
end

Will look for all templates at “app/views/notifier” with name “welcome”. If no welcome template exists, it will raise an ActionView::MissingTemplate error.

However, those can be customized:

mail(template_path: 'notifications', template_name: 'another')

And now it will look for all templates at “app/views/notifications” with name “another”.

If you do pass a block, you can render specific templates of your choice:

mail(to: 'mikel@test.lindsaar.net') do |format|
  format.text
  format.html
end

You can even render plain text directly without using a template:

mail(to: 'mikel@test.lindsaar.net') do |format|
  format.text { render plain: "Hello Mikel!" }
  format.html { render html: "<h1>Hello Mikel!</h1>".html_safe }
end

Which will render a multipart/alternative email with text/plain and text/html parts.

The block syntax also allows you to customize the part headers if desired:

mail(to: 'mikel@test.lindsaar.net') do |format|
  format.text(content_transfer_encoding: "base64")
  format.html
end

# File actionmailer/lib/action_mailer/base.rb, line 759
    def mail(headers = {}, &block)
      return @_message if @_mail_was_called && headers.blank? && !block

      m = @_message

      # At the beginning, do not consider class default for content_type
      content_type = headers[:content_type]

      # Call all the procs (if any)
      default_values = {}
      self.class.default.each do |k,v|
        default_values[k] = v.is_a?(Proc) ? instance_eval(&v) : v
      end

      # Handle defaults
      headers = headers.reverse_merge(default_values)
      headers[:subject] ||= default_i18n_subject

      # Apply charset at the beginning so all fields are properly quoted
      m.charset = charset = headers[:charset]

      # Set configure delivery behavior
      wrap_delivery_behavior!(headers.delete(:delivery_method), headers.delete(:delivery_method_options))

      # Assign all headers except parts_order, content_type and body
      assignable = headers.except(:parts_order, :content_type, :body, :template_name, :template_path)
      assignable.each { |k, v| m[k] = v }

      # Render the templates and blocks
      responses = collect_responses(headers, &block)
      @_mail_was_called = true

      create_parts_from_responses(m, responses)

      # Setup content type, reapply charset and handle parts order
      m.content_type = set_content_type(m, content_type, headers[:content_type])
      m.charset      = charset

      if m.multipart?
        m.body.set_sort_order(headers[:parts_order])
        m.body.sort_parts!
      end

      m
    end