2004-11-23 20:04:44 -05:00
= Action Mailer -- Easy email delivery and testing
2005-10-26 09:04:20 -04:00
Action Mailer is a framework for designing email-service layers. These layers
2006-09-02 15:32:45 -04:00
are used to consolidate code for sending out forgotten passwords, welcome
2004-11-23 20:04:44 -05:00
wishes on signup, invoices for billing, and any other use case that requires
a written notification to either a person or another system.
2010-08-14 01:13:00 -04:00
Action Mailer is in essence a wrapper around Action Controller and the
2010-01-25 07:46:09 -05:00
Mail gem. It provides a way to make emails using templates in the same
way that Action Controller renders views using templates.
2005-03-20 12:51:11 -05:00
Additionally, an Action Mailer class can be used to process incoming email,
such as allowing a weblog to accept new posts from an email (which could even
have been sent from a phone).
== Sending emails
2010-01-25 07:46:09 -05:00
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'
2010-08-14 01:13:00 -04:00
2010-01-25 07:46:09 -05:00
def welcome(recipient)
@recipient = recipient
mail(:to => recipient,
:subject => "[Signed up] Welcome #{recipient}")
end
2004-11-23 20:04:44 -05:00
end
The body of the email is created by using an Action View template (regular
2011-04-03 03:59:37 -04:00
ERB) that has the instance variables that are declared in the mailer action.
2010-01-25 07:46:09 -05:00
2004-11-23 20:04:44 -05:00
So the corresponding body template for the method above could look like this:
2010-08-14 01:13:00 -04:00
Hello there,
2004-11-23 20:04:44 -05:00
Mr. <%= @recipient %>
2010-01-25 07:46:09 -05:00
Thank you for signing up!
2010-08-14 01:13:00 -04:00
And if the recipient was given as "david@loudthinking.com", the email
2004-11-23 20:04:44 -05:00
generated would look like this:
2010-01-25 07:46:09 -05:00
Date: Mon, 25 Jan 2010 22:48:09 +1100
2004-11-23 20:04:44 -05:00
From: system@loudthinking.com
To: david@loudthinking.com
2010-01-25 07:46:09 -05:00
Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail>
2004-11-23 20:04:44 -05:00
Subject: [Signed up] Welcome david@loudthinking.com
2010-01-25 07:46:09 -05:00
Mime-Version: 1.0
Content-Type: text/plain;
charset="US-ASCII";
Content-Transfer-Encoding: 7bit
2004-11-23 20:04:44 -05:00
2010-08-14 01:13:00 -04:00
Hello there,
2004-11-23 20:04:44 -05:00
Mr. david@loudthinking.com
2010-12-19 14:37:33 -05:00
In previous version of Rails you would call <tt>create_method_name</tt> and
2010-01-25 07:46:09 -05:00
<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:
2010-08-12 11:09:58 -04:00
message = Notifier.welcome # => Returns a Mail::Message object
message.deliver # => delivers the email
2004-11-23 20:04:44 -05:00
2010-01-25 07:46:09 -05:00
Or you can just chain the methods together like:
Notifier.welcome.deliver # Creates the email and sends it immediately
2004-11-23 20:04:44 -05:00
2011-04-03 07:17:26 -04:00
== Setting defaults
2011-04-03 12:12:07 -04:00
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 wont need to worry about that. Finally it is also possible to pass in a Proc that will get evaluated when it is needed.
2011-04-03 07:17:26 -04:00
2011-04-03 12:12:07 -04:00
Note that every value you set with this method will get over written if you use the same key in your mailer method.
2011-04-03 07:17:26 -04:00
Example:
class Authenticationmailer < ActionMailer::Base
2011-04-03 12:12:07 -04:00
default :from => "awesome@application.com", :subject => Proc.new { "E-mail was generated at #{Time.now}" }
2011-04-03 07:17:26 -04:00
.....
end
2005-03-20 12:51:11 -05:00
== Receiving emails
2011-03-06 15:52:47 -05:00
To receive emails, you need to implement a public instance method called <tt>receive</tt> that takes an
2011-03-04 19:38:21 -05:00
email object as its single parameter. The Action Mailer framework has a corresponding class method,
2010-07-28 21:50:24 -04:00
which is also called <tt>receive</tt>, that accepts a raw, unprocessed email as a string, which it then turns
2011-03-04 19:38:21 -05:00
into the email object and calls the receive instance method.
2005-03-20 12:51:11 -05:00
Example:
class Mailman < ActionMailer::Base
def receive(email)
page = Page.find_by_address(email.to.first)
page.emails.create(
2005-03-21 07:10:47 -05:00
:subject => email.subject, :body => email.body
2005-03-20 12:51:11 -05:00
)
if email.has_attachments?
2011-05-18 23:47:49 -04:00
email.attachments.each do |attachment|
2010-08-14 01:13:00 -04:00
page.attachments.create({
2005-03-21 07:10:47 -05:00
:file => attachment, :description => email.subject
2005-03-20 12:51:11 -05:00
})
end
end
end
end
2010-08-14 01:13:00 -04:00
This Mailman can be the target for Postfix or other MTAs. In Rails, you would use the runner in the
2008-05-16 18:01:32 -04:00
trivial case like this:
2005-03-20 12:51:11 -05:00
2010-02-06 11:18:10 -05:00
rails runner 'Mailman.receive(STDIN.read)'
2005-03-20 12:51:11 -05:00
2010-08-14 01:13:00 -04:00
However, invoking Rails in the runner for each mail to be received is very resource intensive. A single
2011-03-04 19:38:21 -05:00
instance of Rails should be run within a daemon, if it is going to be utilized to process more than just
2008-05-16 18:01:32 -04:00
a limited number of email.
2005-07-09 13:18:01 -04:00
== Configuration
The Base class has the full list of configuration options. Here's an example:
2008-05-16 18:01:32 -04:00
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
}
2004-11-23 20:04:44 -05:00
2010-07-18 08:58:40 -04:00
== Download and installation
2004-11-23 20:04:44 -05:00
2010-07-21 05:56:28 -04:00
The latest version of Action Mailer can be installed with Rubygems:
2004-11-23 20:04:44 -05:00
2010-07-18 08:58:40 -04:00
% [sudo] gem install actionmailer
Source code can be downloaded as part of the Rails project on GitHub
2004-11-23 20:04:44 -05:00
2011-03-06 15:56:02 -05:00
* https://github.com/rails/rails/tree/master/actionmailer/
2004-11-23 20:04:44 -05:00
== License
Action Mailer is released under the MIT license.
2010-07-18 08:58:40 -04:00
2004-11-23 20:04:44 -05:00
== Support
2010-07-18 08:58:40 -04:00
API documentation is at
2011-05-24 11:42:01 -04:00
* http://api.rubyonrails.org
2010-07-18 08:58:40 -04:00
Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
2004-11-23 20:04:44 -05:00
2011-05-10 12:30:06 -04:00
* https://github.com/rails/rails/issues
2011-03-04 19:38:21 -05:00