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