mirror of
https://github.com/rails/rails.git
synced 2022-11-09 12:12:34 -05:00
729741a3fa
git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8321 5ecf4fe2-1ee6-0310-87b1-e25e094e27de |
||
---|---|---|
.. | ||
lib | ||
test | ||
CHANGELOG | ||
install.rb | ||
MIT-LICENSE | ||
Rakefile | ||
README |
= 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. 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.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.