vendor/rails/actionmailer/README

   1 = Action Mailer -- Easy email delivery and testing
   2
   3 Action Mailer is a framework for designing email-service layers. These layers
   4 are used to consolidate code for sending out forgotten passwords, welcome
   5 wishes on signup, invoices for billing, and any other use case that requires
   6 a written notification to either a person or another system.
   7
   8 Additionally, an Action Mailer class can be used to process incoming email,
   9 such as allowing a weblog to accept new posts from an email (which could even
  10 have been sent from a phone).
  11
  12 == Sending emails
  13
  14 The framework works by setting up all the email details, except the body,
  15 in methods on the service layer. Subject, recipients, sender, and timestamp
  16 are all set up this way. An example of such a method:
  17
  18   def signed_up(recipient)
  19     recipients recipient
  20     subject    "[Signed up] Welcome #{recipient}"
  21     from       "system@loudthinking.com"
  22
  23     body(:recipient => recipient)
  24   end
  25
  26 The body of the email is created by using an Action View template (regular
  27 ERb) that has the content of the body hash parameter available as instance variables.
  28 So the corresponding body template for the method above could look like this:
  29
  30   Hello there,
  31
  32   Mr. <%= @recipient %>
  33
  34 And if the recipient was given as "david@loudthinking.com", the email
  35 generated would look like this:
  36
  37   Date: Sun, 12 Dec 2004 00:00:00 +0100
  38   From: system@loudthinking.com
  39   To: david@loudthinking.com
  40   Subject: [Signed up] Welcome david@loudthinking.com
  41
  42   Hello there,
  43
  44   Mr. david@loudthinking.com
  45
  46 You never actually call the instance methods like signed_up directly. Instead,
  47 you call class methods like deliver_* and create_* that are automatically
  48 created for each instance method. So if the signed_up method sat on
  49 ApplicationMailer, it would look like this:
  50
  51   ApplicationMailer.create_signed_up("david@loudthinking.com")  # => tmail object for testing
  52   ApplicationMailer.deliver_signed_up("david@loudthinking.com") # sends the email
  53   ApplicationMailer.new.signed_up("david@loudthinking.com")     # won't work!
  54
  55 == Receiving emails
  56
  57 To receive emails, you need to implement a public instance method called receive that takes a
  58 tmail object as its single parameter. The Action Mailer framework has a corresponding class method,
  59 which is also called receive, that accepts a raw, unprocessed email as a string, which it then turns
  60 into the tmail object and calls the receive instance method.
  61
  62 Example:
  63
  64   class Mailman < ActionMailer::Base
  65     def receive(email)
  66       page = Page.find_by_address(email.to.first)
  67       page.emails.create(
  68         :subject => email.subject, :body => email.body
  69       )
  70
  71       if email.has_attachments?
  72         for attachment in email.attachments
  73           page.attachments.create({
  74             :file => attachment, :description => email.subject
  75           })
  76         end
  77       end
  78     end
  79   end
  80
  81 This Mailman can be the target for Postfix. In Rails, you would use the runner like this:
  82
  83   ./script/runner 'Mailman.receive(STDIN.read)'
  84
  85 == Configuration
  86
  87 The Base class has the full list of configuration options. Here's an example:
  88
  89 ActionMailer::Base.smtp_settings = {
  90   :address=>'smtp.yourserver.com',    # default: localhost
  91   :port=>'25',                        # default: 25
  92   :user_name=>'user',
  93   :password=>'pass',
  94   :authentication=>:plain             # :plain, :login or :cram_md5
  95 }
  96
  97 == Dependencies
  98
  99 Action Mailer requires that the Action Pack is either available to be required immediately
 100 or is accessible as a GEM.
 101
 102
 103 == Bundled software
 104
 105 * tmail 0.10.8 by Minero Aoki released under LGPL
 106   Read more on http://i.loveruby.net/en/prog/tmail.html
 107
 108 * Text::Format 0.63 by Austin Ziegler released under OpenSource
 109   Read more on http://www.halostatue.ca/ruby/Text__Format.html
 110
 111
 112 == Download
 113
 114 The latest version of Action Mailer can be found at
 115
 116 * http://rubyforge.org/project/showfiles.php?group_id=361
 117
 118 Documentation can be found at
 119
 120 * http://actionmailer.rubyonrails.org
 121
 122
 123 == Installation
 124
 125 You can install Action Mailer with the following command.
 126
 127   % [sudo] ruby install.rb
 128
 129 from its distribution directory.
 130
 131
 132 == License
 133
 134 Action Mailer is released under the MIT license.
 135
 136
 137 == Support
 138
 139 The Action Mailer homepage is http://www.rubyonrails.org. You can find
 140 the Action Mailer RubyForge page at http://rubyforge.org/projects/actionmailer.
 141 And as Jim from Rake says:
 142
 143    Feel free to submit commits or feature requests.  If you send a patch,
 144    remember to update the corresponding unit tests.  If fact, I prefer
 145    new feature to be submitted in the form of new unit tests.