README.rdoc

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.

In previous version of Rails you would call create_method_name and
deliver_method_name. Rails 3.0 has a much simpler interface, you
simply call the method and optionally call deliver on the return
value.

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 default 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 :from 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.

Receiving emails

To receive emails, you need to implement a public instance method called
receive that takes an email object as its single parameter. The
Action Mailer framework has a corresponding class method, which is also
called receive, that accepts a raw, unprocessed email as a string,
which it then turns into the email object and calls the receive instance
method.

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: