Method: ActionMailer::Base#mail

Defined in:
actionmailer/lib/action_mailer/base.rb

#mail(headers = {}, &block) ⇒ Object

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.

It accepts 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: '[email protected]',
          bcc: '[email protected]',
          reply_to: '[email protected]'
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: '[email protected]'

  def welcome
    mail(to: '[email protected]')
  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: '[email protected]') do |format|
  format.text
  format.html
end

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

mail(to: '[email protected]') 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: '[email protected]') do |format|
  format.text(content_transfer_encoding: "base64")
  format.html
end



864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
 
# File 'actionmailer/lib/action_mailer/base.rb', line 864

def mail(headers = {}, &block)
  return message if @_mail_was_called && headers.blank? && !block

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

  headers = apply_defaults(headers)

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

  # Set configure delivery behavior
  wrap_delivery_behavior!(headers[:delivery_method], headers[:delivery_method_options])

  assign_headers_to_message(message, headers)

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

  create_parts_from_responses(message, responses)
  wrap_inline_attachments(message)

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

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

  message
end