--- /dev/null
+= 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.
+
+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 or other MTAs. In Rails, you would use the runner in the
+trivial case like this:
+
+ ./script/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
+ }
+
+== 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://www.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.
projects / depot.git / blobdiff