2004-11-23 20:04:44 -05:00
|
|
|
= Action Mailer -- Easy email delivery and testing
|
|
|
|
|
2013-03-11 18:41:44 -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,
|
2011-07-30 21:27:08 -04:00
|
|
|
such as allowing a blog to accept new posts from an email (which could even
|
2005-03-20 12:51:11 -05:00
|
|
|
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
|
2012-04-28 00:58:15 -04:00
|
|
|
default 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
|
2012-04-28 00:58:15 -04:00
|
|
|
mail(to: recipient,
|
|
|
|
subject: "[Signed up] Welcome #{recipient}")
|
2010-01-25 07:46:09 -05:00
|
|
|
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
|
|
|
|
2011-12-23 00:10:01 -05:00
|
|
|
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
|
|
|
|
|
2011-09-26 13:46:25 -04:00
|
|
|
Thank you for signing up!
|
|
|
|
|
2014-10-31 15:37:43 -04:00
|
|
|
In order to send mails, you simply call the method and then call +deliver_now+ on the return value.
|
2010-01-25 07:46:09 -05:00
|
|
|
|
|
|
|
Calling the method returns a Mail Message object:
|
|
|
|
|
2014-08-20 08:34:37 -04:00
|
|
|
message = Notifier.welcome("david@loudthinking.com") # => Returns a Mail::Message object
|
|
|
|
message.deliver_now # => 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:
|
|
|
|
|
2014-08-20 08:34:37 -04:00
|
|
|
Notifier.welcome("david@loudthinking.com").deliver_now # 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
|
|
|
|
|
2014-11-02 06:32:50 -05: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 +default+ which you get for free from <tt>ActionMailer::Base</tt>.
|
|
|
|
This method accepts a Hash as the parameter. You can use any of the headers,
|
|
|
|
email messages have, 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 overwritten if you use the
|
|
|
|
same key in your mailer method.
|
2011-04-03 07:17:26 -04:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
2012-02-12 01:52:12 -05:00
|
|
|
class AuthenticationMailer < ActionMailer::Base
|
2012-10-10 07:45:47 -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
|
|
|
|
|
2014-11-02 06:32:50 -05:00
|
|
|
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.
|
2005-03-20 12:51:11 -05:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
class Mailman < ActionMailer::Base
|
|
|
|
def receive(email)
|
2013-01-14 23:21:03 -05:00
|
|
|
page = Page.find_by(address: email.to.first)
|
2005-03-20 12:51:11 -05:00
|
|
|
page.emails.create(
|
2012-10-10 07:45:47 -04:00
|
|
|
subject: email.subject, body: email.body
|
2005-03-20 12:51:11 -05:00
|
|
|
)
|
|
|
|
|
|
|
|
if email.has_attachments?
|
2014-02-23 04:19:15 -05:00
|
|
|
email.attachments.each do |attachment|
|
2010-08-14 01:13:00 -04:00
|
|
|
page.attachments.create({
|
2012-10-10 07:45:47 -04:00
|
|
|
file: attachment, description: email.subject
|
2005-03-20 12:51:11 -05:00
|
|
|
})
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2014-11-02 06:32:50 -05:00
|
|
|
This Mailman can be the target for Postfix or other MTAs. In Rails, you would use
|
|
|
|
the runner in the 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
|
|
|
|
2014-11-02 06:32:50 -05:00
|
|
|
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 process more than just a limited amount of email.
|
2008-05-16 18:01:32 -04:00
|
|
|
|
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 = {
|
2012-10-10 07:45:47 -04:00
|
|
|
address: 'smtp.yourserver.com', # default: localhost
|
|
|
|
port: '25', # default: 25
|
|
|
|
user_name: 'user',
|
|
|
|
password: 'pass',
|
|
|
|
authentication: :plain # :plain, :login or :cram_md5
|
2008-05-16 18:01:32 -04:00
|
|
|
}
|
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
|
|
|
|
2011-08-05 04:34:43 -04:00
|
|
|
The latest version of Action Mailer can be installed with RubyGems:
|
2004-11-23 20:04:44 -05:00
|
|
|
|
2015-05-12 17:51:19 -04:00
|
|
|
% gem install actionmailer
|
2010-07-18 08:58:40 -04:00
|
|
|
|
|
|
|
Source code can be downloaded as part of the Rails project on GitHub
|
2004-11-23 20:04:44 -05:00
|
|
|
|
2011-08-04 00:43:55 -04:00
|
|
|
* https://github.com/rails/rails/tree/master/actionmailer
|
2004-11-23 20:04:44 -05:00
|
|
|
|
|
|
|
|
|
|
|
== License
|
|
|
|
|
2011-12-23 00:13:28 -05:00
|
|
|
Action Mailer is released under the MIT license:
|
|
|
|
|
|
|
|
* http://www.opensource.org/licenses/MIT
|
2004-11-23 20:04:44 -05:00
|
|
|
|
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
|
|
|
|
2014-06-01 22:11:39 -04:00
|
|
|
Bug reports can be filed 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
|
|
|
|
2014-06-01 22:11:39 -04:00
|
|
|
Feature requests should be discussed on the rails-core mailing list here:
|
|
|
|
|
|
|
|
* https://groups.google.com/forum/?fromgroups#!forum/rubyonrails-core
|
|
|
|
|