Class: ActionMailer::Base
- Inherits:
-
Object
- Object
- ActionMailer::Base
- Includes:
- AdvAttrAccessor, PartContainer, Reloadable::Subclasses
- Defined in:
- lib/action_mailer/base.rb
Overview
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 "[email protected]"
end
# explicitly specify multipart messages
def signup_notification(recipient)
recipients recipient.email_address_with_name
subject "New account information"
from "[email protected]"
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
# 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
# implicitly multipart messages
def signup_notification(recipient)
recipients recipient.email_address_with_name
subject "New account information"
from "[email protected]"
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
.
Constant Summary collapse
- @@server_settings =
{ :address => "localhost", :port => 25, :domain => 'localhost.localdomain', :user_name => nil, :password => nil, :authentication => nil }
- @@raise_delivery_errors =
true
- @@delivery_method =
:smtp
- @@perform_deliveries =
true
- @@deliveries =
[]
- @@default_charset =
"utf-8"
- @@default_content_type =
"text/plain"
- @@default_mime_version =
nil
- @@default_implicit_parts_order =
[ "text/html", "text/enriched", "text/plain" ]
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.
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.
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).
266 267 268 |
# File 'lib/action_mailer/base.rb', line 266 def initialize(method_name=nil, *parameters) #:nodoc: create!(method_name, *parameters) if method_name end |
Instance Attribute Details
#mail ⇒ Object (readonly)
The mail object instance referenced by this mailer.
221 222 223 |
# File 'lib/action_mailer/base.rb', line 221 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)
257 258 259 |
# File 'lib/action_mailer/base.rb', line 257 def deliver(mail) new.deliver!(mail) end |
.method_missing(method_symbol, *parameters) ⇒ Object
:nodoc:
224 225 226 227 228 229 230 231 |
# File 'lib/action_mailer/base.rb', line 224 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
244 245 246 247 248 249 |
# File 'lib/action_mailer/base.rb', line 244 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 |
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.
272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 |
# File 'lib/action_mailer/base.rb', line 272 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.rhtml", 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| # TODO: don't hardcode rhtml|rxml basename = File.basename(path) next unless md = /^([^\.]+)\.([^\.]+\.[^\+]+)\.(rhtml|rxml)$/.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.
328 329 330 331 332 333 334 335 336 337 338 339 |
# File 'lib/action_mailer/base.rb', line 328 def deliver!(mail = @mail) raise "no mail object available for delivery!" unless mail logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil? begin send("perform_delivery_#{delivery_method}", mail) if perform_deliveries rescue Object => e raise e if raise_delivery_errors end return mail end |