149 lines
4.6 KiB
Plaintext
Executable file
149 lines
4.6 KiB
Plaintext
Executable file
= 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, welcoming
|
|
wishes on signup, invoices for billing, and any other use case that requires
|
|
a written notification to either a person or another system.
|
|
|
|
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
|
|
|
|
The framework works by setting up all the email details, except the body,
|
|
in methods on the service layer. Subject, recipients, sender, and timestamp
|
|
are all set up this way. An example of such a method:
|
|
|
|
def signed_up(recipient)
|
|
recipients recipient
|
|
subject "[Signed up] Welcome #{recipient}"
|
|
from "system@loudthinking.com"
|
|
|
|
body(:recipient => recipient)
|
|
end
|
|
|
|
The body of the email is created by using an Action View template (regular
|
|
ERb) that has the content of the body hash parameter available as instance variables.
|
|
So the corresponding body template for the method above could look like this:
|
|
|
|
Hello there,
|
|
|
|
Mr. <%= @recipient %>
|
|
|
|
And if the recipient was given as "david@loudthinking.com", the email
|
|
generated would look like this:
|
|
|
|
Date: Sun, 12 Dec 2004 00:00:00 +0100
|
|
From: system@loudthinking.com
|
|
To: david@loudthinking.com
|
|
Subject: [Signed up] Welcome david@loudthinking.com
|
|
|
|
Hello there,
|
|
|
|
Mr. david@loudthinking.com
|
|
|
|
You never actually call the instance methods like signed_up directly. Instead,
|
|
you call class methods like deliver_* and create_* that are automatically
|
|
created for each instance method. So if the signed_up method sat on
|
|
ApplicationMailer, it would look like this:
|
|
|
|
ApplicationMailer.create_signed_up("david@loudthinking.com") # => tmail object for testing
|
|
ApplicationMailer.deliver_signed_up("david@loudthinking.com") # sends the email
|
|
ApplicationMailer.new.signed_up("david@loudthinking.com") # won't work!
|
|
|
|
== Receiving emails
|
|
|
|
To receive emails, you need to implement a public instance method called receive that takes a
|
|
tmail 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 tmail 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?
|
|
for attachment in email.attachments
|
|
page.attachments.create({
|
|
:file => attachment, :description => email.subject
|
|
})
|
|
end
|
|
end
|
|
end
|
|
end
|
|
|
|
This Mailman can be the target for Postfix. In Rails, you would use the runner like this:
|
|
|
|
./script/runner 'Mailman.receive(STDIN.read)'
|
|
|
|
== Configuration
|
|
|
|
The Base class has the full list of configuration options. Here's an example:
|
|
|
|
ActionMailer::Base.server_settings = {
|
|
:address=>'smtp.yourserver.com', # default: localhost
|
|
:port=>'25', # default: 25
|
|
:user_name=>'user',
|
|
:password=>'pass',
|
|
:authentication=>:plain # :plain, :login or :cram_md5
|
|
}
|
|
|
|
== Dependencies
|
|
|
|
Action Mailer requires that the Action Pack is either available to be required immediately
|
|
or is accessible as a GEM.
|
|
|
|
|
|
== Bundled software
|
|
|
|
* tmail 0.10.8 by Minero Aoki released under LGPL
|
|
Read more on http://i.loveruby.net/en/prog/tmail.html
|
|
|
|
* Text::Format 0.63 by Austin Ziegler released under OpenSource
|
|
Read more on http://www.halostatue.ca/ruby/Text__Format.html
|
|
|
|
|
|
== Download
|
|
|
|
The latest version of Action Mailer can be found at
|
|
|
|
* http://rubyforge.org/project/showfiles.php?group_id=361
|
|
|
|
Documentation can be found at
|
|
|
|
* http://actionmailer.rubyonrails.org
|
|
|
|
|
|
== Installation
|
|
|
|
You can install Action Mailer with the following command.
|
|
|
|
% [sudo] ruby install.rb
|
|
|
|
from its distribution directory.
|
|
|
|
|
|
== License
|
|
|
|
Action Mailer is released under the MIT license.
|
|
|
|
|
|
== Support
|
|
|
|
The Action Mailer homepage is http://actionmailer.rubyonrails.org. You can find
|
|
the Action Mailer RubyForge page at http://rubyforge.org/projects/actionmailer.
|
|
And as Jim from Rake says:
|
|
|
|
Feel free to submit commits or feature requests. If you send a patch,
|
|
remember to update the corresponding unit tests. If fact, I prefer
|
|
new feature to be submitted in the form of new unit tests.
|
|
|
|
For other information, feel free to ask on the ruby-talk mailing list (which
|
|
is mirrored to comp.lang.ruby) or contact mailto:david@loudthinking.com.
|