Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 164 lines (108 sloc) 5.64 kB
db045db @dhh Initial
dhh authored
1 = Action Mailer -- Easy email delivery and testing
2
475bd74 @dhh Fix docs (closes #2598)
dhh authored
3 Action Mailer is a framework for designing email-service layers. These layers
20bd4bd @dhh Updated docs and otherwise
dhh authored
4 are used to consolidate code for sending out forgotten passwords, welcome
db045db @dhh Initial
dhh authored
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
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
8 Action Mailer is in essence a wrapper around Action Controller and the
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
9 Mail gem. It provides a way to make emails using templates in the same
10 way that Action Controller renders views using templates.
11
800b86e @dhh Added framework support for processing incoming emails with an Action…
dhh authored
12 Additionally, an Action Mailer class can be used to process incoming email,
a98eca8 @waynn "blog" is more common than "weblog" these days.
waynn authored
13 such as allowing a blog to accept new posts from an email (which could even
800b86e @dhh Added framework support for processing incoming emails with an Action…
dhh authored
14 have been sent from a phone).
15
16 == Sending emails
17
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
18 The framework works by initializing any instance variables you want to be
19 available in the email template, followed by a call to +mail+ to deliver
20 the email.
21
22 This can be as simple as:
23
24 class Notifier < ActionMailer::Base
25 delivers_from 'system@loudthinking.com'
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
26
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
27 def welcome(recipient)
28 @recipient = recipient
29 mail(:to => recipient,
30 :subject => "[Signed up] Welcome #{recipient}")
31 end
db045db @dhh Initial
dhh authored
32 end
33
34 The body of the email is created by using an Action View template (regular
9bf5cdd @amatsuda s/ERb/ERB/g (part II)
amatsuda authored
35 ERB) that has the instance variables that are declared in the mailer action.
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
36
db045db @dhh Initial
dhh authored
37 So the corresponding body template for the method above could look like this:
38
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
39 Hello there,
db045db @dhh Initial
dhh authored
40
41 Mr. <%= @recipient %>
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
42
43 Thank you for signing up!
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
44
45 And if the recipient was given as "david@loudthinking.com", the email
db045db @dhh Initial
dhh authored
46 generated would look like this:
47
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
48 Date: Mon, 25 Jan 2010 22:48:09 +1100
db045db @dhh Initial
dhh authored
49 From: system@loudthinking.com
50 To: david@loudthinking.com
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
51 Message-ID: <4b5d84f9dd6a5_7380800b81ac29578@void.loudthinking.com.mail>
db045db @dhh Initial
dhh authored
52 Subject: [Signed up] Welcome david@loudthinking.com
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
53 Mime-Version: 1.0
54 Content-Type: text/plain;
55 charset="US-ASCII";
56 Content-Transfer-Encoding: 7bit
db045db @dhh Initial
dhh authored
57
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
58 Hello there,
db045db @dhh Initial
dhh authored
59
60 Mr. david@loudthinking.com
61
893ee7f @avakhov fix ActionMailer readme example
avakhov authored
62 Thank you for signing up!
63
4038a6b @vijaydev minor fixesin READMEs
vijaydev authored
64 In previous version of Rails you would call <tt>create_method_name</tt> and
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
65 <tt>deliver_method_name</tt>. Rails 3.0 has a much simpler interface, you
66 simply call the method and optionally call +deliver+ on the return value.
67
68 Calling the method returns a Mail Message object:
69
8a2b69b @pacoguzman applied guidelines to "# =>"
pacoguzman authored
70 message = Notifier.welcome # => Returns a Mail::Message object
71 message.deliver # => delivers the email
db045db @dhh Initial
dhh authored
72
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
73 Or you can just chain the methods together like:
74
75 Notifier.welcome.deliver # Creates the email and sends it immediately
db045db @dhh Initial
dhh authored
76
f323a8f @simply-phi Added information about default values
simply-phi authored
77 == Setting defaults
78
55296ec @waynn typo in "wont"
waynn authored
79 It is possible to set default values that will be used in every method in your Action Mailer class. To implement this functionality, you just call the public class method <tt>default</tt> which you get for free from ActionMailer::Base. This method accepts a Hash as the parameter. You can use any of the headers e-mail messages has, like <tt>:from</tt> as the key. You can also pass in a string as the key, like "Content-Type", but Action Mailer does this out of the box for you, so you won't need to worry about that. Finally it is also possible to pass in a Proc that will get evaluated when it is needed.
f323a8f @simply-phi Added information about default values
simply-phi authored
80
ac07da8 @simply-phi Made the defaults section a little more readable and more to the poin…
simply-phi authored
81 Note that every value you set with this method will get over written if you use the same key in your mailer method.
f323a8f @simply-phi Added information about default values
simply-phi authored
82
83 Example:
84
85 class Authenticationmailer < ActionMailer::Base
ac07da8 @simply-phi Made the defaults section a little more readable and more to the poin…
simply-phi authored
86 default :from => "awesome@application.com", :subject => Proc.new { "E-mail was generated at #{Time.now}" }
f323a8f @simply-phi Added information about default values
simply-phi authored
87 .....
88 end
89
800b86e @dhh Added framework support for processing incoming emails with an Action…
dhh authored
90 == Receiving emails
91
112c802 @amatsuda s/a/an/
amatsuda authored
92 To receive emails, you need to implement a public instance method called <tt>receive</tt> that takes an
b12a4a9 @judearasu typo changes
judearasu authored
93 email object as its single parameter. The Action Mailer framework has a corresponding class method,
2df3655 @neerajdotname putting receive method under tt
neerajdotname authored
94 which is also called <tt>receive</tt>, that accepts a raw, unprocessed email as a string, which it then turns
b12a4a9 @judearasu typo changes
judearasu authored
95 into the email object and calls the receive instance method.
800b86e @dhh Added framework support for processing incoming emails with an Action…
dhh authored
96
97 Example:
98
99 class Mailman < ActionMailer::Base
100 def receive(email)
101 page = Page.find_by_address(email.to.first)
102 page.emails.create(
cb69736 @dhh Made the unquoted subject and body the default
dhh authored
103 :subject => email.subject, :body => email.body
800b86e @dhh Added framework support for processing incoming emails with an Action…
dhh authored
104 )
105
106 if email.has_attachments?
e3eaeb4 @arunagw Example Usage updated for actionpack and actionmailer.
arunagw authored
107 email.attachments.each do |attachment|
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
108 page.attachments.create({
cb69736 @dhh Made the unquoted subject and body the default
dhh authored
109 :file => attachment, :description => email.subject
800b86e @dhh Added framework support for processing incoming emails with an Action…
dhh authored
110 })
111 end
112 end
113 end
114 end
115
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
116 This Mailman can be the target for Postfix or other MTAs. In Rails, you would use the runner in the
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
117 trivial case like this:
800b86e @dhh Added framework support for processing incoming emails with an Action…
dhh authored
118
f44a0b1 @romdi fix usage examples and more to use new invocations
romdi authored
119 rails runner 'Mailman.receive(STDIN.read)'
800b86e @dhh Added framework support for processing incoming emails with an Action…
dhh authored
120
b451de0 @spastorino Deletes trailing whitespaces (over text files only find * -type f -ex…
spastorino authored
121 However, invoking Rails in the runner for each mail to be received is very resource intensive. A single
b12a4a9 @judearasu typo changes
judearasu authored
122 instance of Rails should be run within a daemon, if it is going to be utilized to process more than just
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
123 a limited number of email.
124
0fe8e3d @dhh Added a config example in README #1626 [courtenay]
dhh authored
125 == Configuration
126
127 The Base class has the full list of configuration options. Here's an example:
128
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
129 ActionMailer::Base.smtp_settings = {
130 :address => 'smtp.yourserver.com', # default: localhost
131 :port => '25', # default: 25
132 :user_name => 'user',
133 :password => 'pass',
134 :authentication => :plain # :plain, :login or :cram_md5
135 }
db045db @dhh Initial
dhh authored
136
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
137
138 == Download and installation
db045db @dhh Initial
dhh authored
139
b905f8c @sukeerthiadiga Rubygems => RubyGems
sukeerthiadiga authored
140 The latest version of Action Mailer can be installed with RubyGems:
db045db @dhh Initial
dhh authored
141
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
142 % [sudo] gem install actionmailer
143
144 Source code can be downloaded as part of the Rails project on GitHub
db045db @dhh Initial
dhh authored
145
21b1a79 @arunagw Updated other README to point 3-2-stable
arunagw authored
146 * https://github.com/rails/rails/tree/3-2-stable/actionmailer
db045db @dhh Initial
dhh authored
147
148
149 == License
150
151 Action Mailer is released under the MIT license.
152
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
153
db045db @dhh Initial
dhh authored
154 == Support
155
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
156 API documentation is at
157
bfb9f75 @Karunakar changed http://api.rubyonrails.com to http://api.rubyonrails.org in …
Karunakar authored
158 * http://api.rubyonrails.org
89b5e79 @mislav revise download/installation/support sections in READMEs
mislav authored
159
160 Bug reports and feature requests can be filed with the rest for the Ruby on Rails project here:
db045db @dhh Initial
dhh authored
161
9870afb @arunagw Some readme fixes as required.
arunagw authored
162 * https://github.com/rails/rails/issues
b12a4a9 @judearasu typo changes
judearasu authored
163
Something went wrong with that request. Please try again.