123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163 |
- = Action Mailer -- Easy email delivery and testing
- Action Mailer is a framework for designing email-service layers. These layers
- are used to consolidate code for sending out forgotten passwords, welcome
- wishes on signup, invoices for billing, and any other use case that requires
- a written notification to either a person or another system.
- Action Mailer is in essence a wrapper around Action Controller and the
- Mail gem. It provides a way to make emails using templates in the same
- way that Action Controller renders views using templates.
- Additionally, an Action Mailer class can be used to process incoming email,
- such as allowing a blog to accept new posts from an email (which could even
- have been sent from a phone).
- == Sending emails
- The framework works by initializing any instance variables you want to be
- available in the email template, followed by a call to +mail+ to deliver
- the email.
- This can be as simple as:
- class Notifier < ActionMailer::Base
- delivers_from 'system@loudthinking.com'
- def welcome(recipient)
- @recipient = recipient
- mail(:to => recipient,
- :subject => "[Signed up] Welcome #{recipient}")
- end
- end
- The body of the email is created by using an Action View template (regular
- ERB) that has the instance variables that are declared in the mailer action.
- So the corresponding body template for the method above could look like this:
- Hello there,
- Mr. <%= @recipient %>
- Thank you for signing up!
- And if the recipient was given as "david@loudthinking.com", the email
- generated would look like this:
- Date: Mon, 25 Jan 2010 22:48:09 +1100
- From: system@loudthinking.com
- To: david@loudthinking.com
- Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail>
- Subject: [Signed up] Welcome david@loudthinking.com
- Mime-Version: 1.0
- Content-Type: text/plain;
- charset="US-ASCII";
- Content-Transfer-Encoding: 7bit
- Hello there,
- Mr. david@loudthinking.com
- Thank you for signing up!
- In previous version of Rails you would call <tt>create_method_name</tt> and
- <tt>deliver_method_name</tt>. Rails 3.0 has a much simpler interface, you
- simply call the method and optionally call +deliver+ on the return value.
- Calling the method returns a Mail Message object:
- message = Notifier.welcome # => Returns a Mail::Message object
- message.deliver # => delivers the email
- Or you can just chain the methods together like:
- Notifier.welcome.deliver # Creates the email and sends it immediately
- == Setting defaults
- It is possible to set default values that will be used in every method in your Action Mailer class. To implement this functionality, you just call the public class method <tt>default</tt> which you get for free from ActionMailer::Base. This method accepts a Hash as the parameter. You can use any of the headers e-mail messages has, like <tt>:from</tt> as the key. You can also pass in a string as the key, like "Content-Type", but Action Mailer does this out of the box for you, so you won't need to worry about that. Finally it is also possible to pass in a Proc that will get evaluated when it is needed.
- Note that every value you set with this method will get over written if you use the same key in your mailer method.
- Example:
- class Authenticationmailer < ActionMailer::Base
- default :from => "awesome@application.com", :subject => Proc.new { "E-mail was generated at #{Time.now}" }
- .....
- end
- == Receiving emails
- To receive emails, you need to implement a public instance method called <tt>receive</tt> that takes an
- email object as its single parameter. The Action Mailer framework has a corresponding class method,
- which is also called <tt>receive</tt>, that accepts a raw, unprocessed email as a string, which it then turns
- into the email object and calls the receive instance method.
- Example:
- class Mailman < ActionMailer::Base
- def receive(email)
- page = Page.find_by_address(email.to.first)
- page.emails.create(
- :subject => email.subject, :body => email.body
- )
- if email.has_attachments?
- email.attachments.each do |attachment|
- page.attachments.create({
- :file => attachment, :description => email.subject
- })
- end
- end
- end
- end
- This Mailman can be the target for Postfix or other MTAs. In Rails, you would use the runner in the
- trivial case like this:
- rails runner 'Mailman.receive(STDIN.read)'
- However, invoking Rails in the runner for each mail to be received is very resource intensive. A single
- instance of Rails should be run within a daemon, if it is going to be utilized to process more than just
- a limited number of email.
- == Configuration
- The Base class has the full list of configuration options. Here's an example:
- ActionMailer::Base.smtp_settings = {
- :address => 'smtp.yourserver.com', # default: localhost
- :port => '25', # default: 25
- :user_name => 'user',
- :password => 'pass',
- :authentication => :plain # :plain, :login or :cram_md5
- }
- == Download and installation
- The latest version of Action Mailer can be installed with RubyGems:
- % [sudo] gem install actionmailer
- Source code can be downloaded as part of the Rails project on GitHub
- * https://github.com/rails/rails/tree/3-2-stable/actionmailer
- == License
- Action Mailer is released under the MIT license.
- == Support
- API documentation is at
- * http://api.rubyonrails.org
- Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
- * https://github.com/rails/rails/issues
|