Class | ActionMailer::Base |
In: |
vendor/rails/actionmailer/lib/action_mailer/base.rb
|
Parent: | Object |
ActionMailer allows you to send email from your application using a mailer model and views.
To use ActionMailer, 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.
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.
Like ActionController, 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 your view includes URLs from the application, you need to use url_for in the mailing method instead of the view. Unlike controllers from Action Pack, the mailer instance doesn‘t have any context about the incoming request. That‘s why you need to jump this little hoop and supply all the details needed for the URL. Example:
def signup_notification(recipient) recipients recipient.email_address_with_name from "[email protected]" subject "New account information" body :account => recipient, :home_page => url_for(:host => "example.com", :controller => "welcome", :action => "greeting") end
You can now access @home_page in the template and get example.com/welcome/greeting.
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.
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" body "account" => recipient from "[email protected]" content_type "text/html" # Here's where the magic happens end end
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]" part :content_type => "text/html", :body => render_message("signup-as-html", :account => recipient) part "text/plain" do |p| p.body = render_message("signup-as-plain", :account => recipient) p.transfer_encoding = "base64" end end end
Multipart messages can also be used implicitly because 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 separate part to the message.
For example, if the following templates existed:
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.
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]" 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
These options are specified on the class level, like ActionMailer::Base.template_root = "/my/templates"
[R] | The mail object instance referenced by this mailer. | |
mailer_name | [W] |
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)
# File vendor/rails/actionmailer/lib/action_mailer/base.rb, line 382 382: def deliver(mail) 383: new.deliver!(mail) 384: end
# File vendor/rails/actionmailer/lib/action_mailer/base.rb, line 341 341: def mailer_name 342: @mailer_name ||= name.underscore 343: end
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
# File vendor/rails/actionmailer/lib/action_mailer/base.rb, line 369 369: def receive(raw_email) 370: logger.info "Received mail:\n #{raw_email}" unless logger.nil? 371: mail = TMail::Mail.parse(raw_email) 372: mail.base64_decode 373: new.receive(mail) 374: end
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')
# File vendor/rails/actionmailer/lib/action_mailer/base.rb, line 393 393: def register_template_extension(extension) 394: template_extensions << extension 395: end
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.
# File vendor/rails/actionmailer/lib/action_mailer/base.rb, line 464 464: def deliver!(mail = @mail) 465: raise "no mail object available for delivery!" unless mail 466: logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil? 467: 468: begin 469: __send__("perform_delivery_#{delivery_method}", mail) if perform_deliveries 470: rescue Exception => e # Net::SMTP errors or sendmail pipe errors 471: raise e if raise_delivery_errors 472: end 473: 474: return mail 475: end
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.
# File vendor/rails/actionmailer/lib/action_mailer/base.rb, line 323 323: def mailer_name(value = nil) 324: if value 325: self.mailer_name = value 326: else 327: self.class.mailer_name 328: end 329: end