Class: ActionMailer::Base
- Includes:
- ActionController::UrlWriter, AdvAttrAccessor, PartContainer
- Defined in:
- lib/action_mailer/base.rb
Overview
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
from "[email protected]"
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 theTo:
header. -
subject
- The subject of your email. Sets theSubject:
header. -
from
- Who the email you are sending is from. Sets theFrom:
header. -
cc
- Takes one or more email addresses. These addresses will receive a carbon copy of your email. Sets theCc:
header. -
bcc
- Takes one or more email addresses. These addresses will receive a blind carbon copy of your email. Sets theBcc:
header. -
reply_to
- Takes one or more email addresses. These addresses will be listed as the default recipients when replying to your email. Sets theReply-To:
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 totext/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
.
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 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) %>
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.[:host] = "example.com"
This can also be set as a configuration option in config/environment.rb
:
config.action_mailer. = { :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 "[email protected]"
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 "[email protected]"
content_type "multipart/alternative"
part :content_type => "text/html",
:body => ("signup-as-html", :account => recipient)
part "text/plain" do |p|
p.body = ("signup-as-plain", :account => recipient)
p.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 "[email protected]"
:content_type => "image/jpeg",
:body => File.read("an-image.jpg")
"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
.
-
-
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
.
-
-
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
. -
perform_deliveries
- Determines whetherdeliver_*
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 withdelivery_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 withcharset
. -
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 withcontent_type
. -
default_mime_version
- The default mime version used for the message. Defaults to1.0
. You can also pick a different value from inside a method withmime_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 withimplicit_parts_order
.
Constant Summary collapse
- @@template_extensions =
['erb', 'builder', 'rhtml', 'rxml']
- @@smtp_settings =
{ :address => "localhost", :port => 25, :domain => 'localhost.localdomain', :user_name => nil, :password => nil, :authentication => nil }
- @@sendmail_settings =
{ :location => '/usr/sbin/sendmail', :arguments => '-i -t' }
- @@raise_delivery_errors =
true
- @@perform_deliveries =
true
- @@deliveries =
[]
- @@default_charset =
"utf-8"
- @@default_content_type =
"text/plain"
- @@default_mime_version =
"1.0"
- @@default_implicit_parts_order =
[ "text/html", "text/enriched", "text/plain" ]
Class Attribute Summary collapse
- .mailer_name ⇒ Object (also: controller_name, controller_path)
Instance Attribute Summary collapse
-
#mail ⇒ Object
readonly
The mail object instance referenced by this mailer.
Attributes included from PartContainer
Class Method Summary collapse
-
.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. -
.register_template_extension(extension) ⇒ Object
Register a template extension so mailer templates written in a templating language other than rhtml or rxml are supported.
- .template_root=(root) ⇒ Object
Instance Method Summary collapse
-
#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.
-
#mailer_name(value = nil) ⇒ Object
Override the mailer name, which defaults to an inflected version of the mailer’s class name.
- #mailer_name=(value) ⇒ Object
Methods included from AdvAttrAccessor
Methods included from PartContainer
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).
438 439 440 |
# File 'lib/action_mailer/base.rb', line 438 def initialize(method_name=nil, *parameters) #:nodoc: create!(method_name, *parameters) if method_name end |
Class Attribute Details
.mailer_name ⇒ Object Also known as: controller_name, controller_path
372 373 374 |
# File 'lib/action_mailer/base.rb', line 372 def mailer_name @mailer_name ||= name.underscore end |
Instance Attribute Details
#mail ⇒ Object (readonly)
The mail object instance referenced by this mailer.
367 368 369 |
# File 'lib/action_mailer/base.rb', line 367 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)
413 414 415 |
# File 'lib/action_mailer/base.rb', line 413 def deliver(mail) new.deliver!(mail) end |
.method_missing(method_symbol, *parameters) ⇒ Object
:nodoc:
380 381 382 383 384 385 386 387 |
# File 'lib/action_mailer/base.rb', line 380 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
400 401 402 403 404 405 |
# File 'lib/action_mailer/base.rb', line 400 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 |
.register_template_extension(extension) ⇒ Object
Register a template extension so mailer templates written in a templating language other than rhtml or rxml are supported. To use this, include in your template-language plugin’s init code or on a per-application basis, this can be invoked from config/environment.rb
:
ActionMailer::Base.register_template_extension('haml')
424 425 426 |
# File 'lib/action_mailer/base.rb', line 424 def register_template_extension(extension) template_extensions << extension 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.
444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 |
# File 'lib/action_mailer/base.rb', line 444 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.erb", 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| basename = File.basename(path) template_regex = Regexp.new("^([^\\\.]+)\\\.([^\\\.]+\\\.[^\\\.]+)\\\.(" + template_extensions.join('|') + ")$") next unless md = template_regex.match(basename) template_name = basename content_type = md.captures[1].gsub('.', '/') @parts << Part.new(:content_type => content_type, :disposition => "inline", :charset => charset, :body => (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 = (@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.
500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 |
# File 'lib/action_mailer/base.rb', line 500 def deliver!(mail = @mail) raise "no mail object available for delivery!" unless mail unless logger.nil? logger.info "Sent mail to #{Array(recipients).join(', ')}" logger.debug "\n#{mail.encoded}" end begin __send__("perform_delivery_#{delivery_method}", mail) if perform_deliveries rescue Exception => e # Net::SMTP errors or sendmail pipe errors raise e if raise_delivery_errors end return mail end |
#mailer_name(value = nil) ⇒ Object
Override the mailer name, which defaults to an inflected version of the mailer’s class name. If you want to use a template in a non-standard location, you can use this to specify that location.
354 355 356 357 358 359 360 |
# File 'lib/action_mailer/base.rb', line 354 def mailer_name(value = nil) if value self.mailer_name = value else self.class.mailer_name end end |
#mailer_name=(value) ⇒ Object
362 363 364 |
# File 'lib/action_mailer/base.rb', line 362 def mailer_name=(value) self.class.mailer_name = value end |