require 'active_support/core_ext/class' require 'active_support/core_ext/module/delegation' require 'mail' require 'action_mailer/tmail_compat' require 'action_mailer/collector' module ActionMailer #:nodoc: # 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 "] # 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 addresses. These addresses will receive a blind carbon copy of your email. Sets the Bcc: header. # * reply_to - Takes one or more email addresses. These addresses will be listed as the default recipients when replying to your email. Sets the Reply-To: header. # * sent_on - The date on which the message was sent. If not set, the header will 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. # # 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. # # # = 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) %> # # If you need to access the subject, from or the recipients in the view, you can do that through mailer object: # # You got a new note from <%= mailer.from %>! # <%= 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" # body :account => recipient # # part :content_type => "text/html", # :data => render_message("signup-as-html") # # part "text/plain" do |p| # p.body = render_message("signup-as-plain") # p.content_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: # * signup_notification.text.plain.erb # * signup_notification.text.html.erb # * signup_notification.text.xml.builder # * signup_notification.text.x-yaml.erb # # 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 # # # = Configuration options # # These options are specified on the class level, like ActionMailer::Base.template_root = "/my/templates" # # * 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. # # * smtp_settings - Allows detailed configuration for :smtp delivery method: # * :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. # * :enable_starttls_auto - When set to true, detects if STARTTLS is enabled in your SMTP server and starts to use it. # It works only on Ruby >= 1.8.7 and Ruby >= 1.9. Default is true. # # * sendmail_settings - Allows you to override options for the :sendmail delivery method. # * :location - The location of the sendmail executable. Defaults to /usr/sbin/sendmail. # * :arguments - The command line arguments. Defaults to -i -t. # # * file_settings - Allows you to override options for the :file delivery method. # * :location - The directory into which emails will be written. Defaults to the application tmp/mails. # # * 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, :test, # and :file. Or you may provide a custom delivery method object eg. MyOwnDeliveryMethodClass.new # # * 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 1.0. You # can also pick a different value from inside a method with +mime_version+. # # * 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+. class Base < AbstractController::Base include Quoting include AbstractController::Logger include AbstractController::Rendering include AbstractController::LocalizedCache include AbstractController::Layouts include AbstractController::Helpers include AbstractController::UrlFor helper ActionMailer::MailHelper include ActionMailer::DeprecatedApi include ActionMailer::DeliveryMethods private_class_method :new #:nodoc: @@raise_delivery_errors = true cattr_accessor :raise_delivery_errors @@perform_deliveries = true cattr_accessor :perform_deliveries # Provides a list of emails that have been delivered by Mail def self.deliveries Mail.deliveries end # Allows you to over write the default deliveries store from an array to some # other object. If you just want to clear the store, call Mail.deliveries.clear. def self.deliveries=(val) Mail.deliveries = val end extlib_inheritable_accessor :default_charset self.default_charset = "utf-8" # TODO This should be used when calling render extlib_inheritable_accessor :default_content_type self.default_content_type = "text/plain" extlib_inheritable_accessor :default_mime_version self.default_mime_version = "1.0" # This specifies the order that the parts of a multipart email will be. Usually you put # text/plain at the top so someone without a MIME capable email reader can read the plain # text of your email first. # # Any content type that is not listed here will be inserted in the order you add them to # the email after the content types you list here. extlib_inheritable_accessor :default_implicit_parts_order self.default_implicit_parts_order = [ "text/plain", "text/enriched", "text/html" ] # Expose the internal Mail message # TODO: Make this an _internal ivar? attr_reader :message def headers(args=nil) if args ActiveSupport::Deprecation.warn "headers(Hash) is deprecated, please do headers[key] = value instead", caller @headers = args else @message end end def attachments @message.attachments end class << self def mailer_name @mailer_name ||= name.underscore end attr_writer :mailer_name alias :controller_path :mailer_name # 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 def receive(raw_mail) ActiveSupport::Notifications.instrument("action_mailer.receive") do |payload| mail = Mail.new(raw_mail) set_payload_for_mail(payload, mail) new.receive(mail) end end def template_root self.view_paths && self.view_paths.first end # Should template root overwrite the whole view_paths? def template_root=(root) self.view_paths = ActionView::Base.process_view_paths(root) end def delivered_email(mail) ActiveSupport::Notifications.instrument("action_mailer.deliver", :mailer => self.name) do |payload| self.set_payload_for_mail(payload, mail) end end def set_payload_for_mail(payload, mail) #:nodoc: payload[:message_id] = mail.message_id payload[:subject] = mail.subject payload[:to] = mail.to payload[:from] = mail.from payload[:bcc] = mail.bcc if mail.bcc.present? payload[:cc] = mail.cc if mail.cc.present? payload[:date] = mail.date payload[:mail] = mail.encoded end end # 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). def initialize(method_name=nil, *args) super() @message = Mail.new process(method_name, *args) if method_name end # TODO Add new delivery method goodness def mail(headers = {}) # Guard flag to prevent both the old and the new API from firing # Should be removed when old API is deprecated @mail_was_called = true m = @message m.register_for_delivery_notification(self.class) # Give preference to headers and fallback to the ones set in mail content_type = headers[:content_type] || m.content_type charset = headers[:charset] || m.charset || self.class.default_charset.dup mime_version = headers[:mime_version] || m.mime_version || self.class.default_mime_version.dup headers[:subject] ||= default_subject quote_fields(m, headers, charset) sort_order = headers[:parts_order] || self.class.default_implicit_parts_order.dup responses = if headers[:body] [ { :body => headers[:body], :content_type => self.class.default_content_type.dup } ] elsif block_given? collector = ActionMailer::Collector.new(self) { render(action_name) } yield(collector) # Collect the sort order of the parts from the collector as Mail will always # sort parts on encode into a "sane" sequence. sort_order = collector.responses.map { |r| r[:content_type] } collector.responses else # TODO Ensure that we don't need to pass I18n.locale as detail templates = self.class.template_root.find_all(action_name, {}, self.class.mailer_name) templates.map do |template| { :body => render_to_body(:_template => template), :content_type => template.mime_type.to_s } end end content_type ||= create_parts_from_responses(m, responses, charset) m.content_type = content_type m.charset = charset m.mime_version = mime_version if m.multipart? m.body.set_sort_order(sort_order) m.body.sort_parts! end m end protected def default_subject #:nodoc: mailer_scope = self.class.mailer_name.gsub('/', '.') I18n.t(:subject, :scope => [:actionmailer, mailer_scope, action_name], :default => action_name.humanize) end def quote_fields(m, headers, charset) #:nodoc: m.subject ||= quote_if_necessary(headers[:subject], charset) if headers[:subject] m.to ||= quote_address_if_necessary(headers[:to], charset) if headers[:to] m.from ||= quote_address_if_necessary(headers[:from], charset) if headers[:from] m.cc ||= quote_address_if_necessary(headers[:cc], charset) if headers[:cc] m.bcc ||= quote_address_if_necessary(headers[:bcc], charset) if headers[:bcc] m.reply_to ||= quote_address_if_necessary(headers[:reply_to], charset) if headers[:reply_to] m.date ||= headers[:date] if headers[:date] end def create_parts_from_responses(m, responses, charset) #:nodoc: if responses.size == 1 && !m.has_attachments? m.body = responses[0][:body] return responses[0][:content_type] elsif responses.size > 1 && m.has_attachments? container = Mail::Part.new container.content_type = "multipart/alternate" responses.each { |r| insert_part(container, r, charset) } m.add_part(container) else responses.each { |r| insert_part(m, r, charset) } end m.has_attachments? ? "multipart/mixed" : "multipart/alternate" end def insert_part(container, response, charset) #:nodoc: response[:charset] ||= charset part = Mail::Part.new(response) container.add_part(part) end end end