Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 718 lines (668 sloc) 30.154 kb
616ebb8 José Valim Remove unused code paths and require mail only when it's needed.
josevalim authored
1 require 'mail'
a288082 Mikel Lindsaar Adding :transfer_encoding -> :content_transfer_encoding as part of Tmail...
mikel authored
2 require 'action_mailer/tmail_compat'
c985a0e Add some tests to collector with templates and any.
José Valim and Mikel Lindsaar authored
3 require 'action_mailer/collector'
41af6d9 Jeremy Kemper Use Array.wrap not Array()
jeremy authored
4 require 'active_support/core_ext/array/wrap'
76f024a Xavier Noria adds missing requires for Object#blank? and Object#present?
fxn authored
5 require 'active_support/core_ext/object/blank'
fa5f936 Santiago Pastorino Added missing require, we are using bind method defined on active_suppor...
spastorino authored
6 require 'active_support/core_ext/proc'
a63caa4 Get tests to run (with failures) without old base around
Yehuda Katz + Carl Lerche authored
7
c4590d5 David Heinemeier Hansson Fixed docs
dhh authored
8 module ActionMailer #:nodoc:
98dc582 Pratik Merge docrails.
lifo authored
9 # Action Mailer allows you to send email from your application using a mailer model and views.
db045db David Heinemeier Hansson Initial
dhh authored
10 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
11 # = Mailer Models
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
12 #
98dc582 Pratik Merge docrails.
lifo authored
13 # To use Action Mailer, you need to create a mailer model.
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
14 #
f44a0b1 Roman Dittert fix usage examples and more to use new invocations
romdi authored
15 # $ rails generate mailer Notifier
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
16 #
058f7fe Mikel Lindsaar Cleaning up Action Mailer spelling with and without the space
mikel authored
17 # The generated model inherits from <tt>ActionMailer::Base</tt>. Emails are defined by creating methods
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
18 # within the model which are then used to set variables to be used in the mail template, to
19 # change options on the mail, or to add attachments.
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
20 #
21 # Examples:
22 #
23 # class Notifier < ActionMailer::Base
452bb1e Jeremy Kemper Rename 'defaults' class method to 'default' to reflect that it's a decla...
jeremy authored
24 # default :from => 'no-reply@example.com',
25 # :return_path => 'system@example.com'
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
26 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
27 # def welcome(recipient)
28 # @account = recipient
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
29 # mail(:to => recipient.email_address_with_name,
30 # :bcc => ["bcc@example.com", "Order Watcher <watcher@example.com>"])
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
31 # end
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
32 # end
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
33 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
34 # Within the mailer method, you have access to the following methods:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
35 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
36 # * <tt>attachments[]=</tt> - Allows you to add attachments to your email in an intuitive
37 # manner; <tt>attachments['filename.png'] = File.read('path/to/filename.png')</tt>
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
38 #
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
39 # * <tt>headers[]=</tt> - Allows you to specify any header field in your email such
40 # as <tt>headers['X-No-Spam'] = 'True'</tt>. Note, while most fields (like <tt>To:</tt>
41 # <tt>From:</tt> can only appear once in an email header, other fields like <tt>X-Anything</tt>
42 # can appear multiple times. If you want to change a field that can appear multiple times,
43 # you need to set it to nil first so that Mail knows you are replacing it, not adding
44 # another field of the same name.)
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
45 #
9520166 Mikel Lindsaar Fixed up being able to pass random headers in with headers, or mail. Al...
mikel authored
46 # * <tt>headers(hash)</tt> - Allows you to specify multiple headers in your email such
47 # as <tt>headers({'X-No-Spam' => 'True', 'In-Reply-To' => '1234@message.id'})</tt>
48 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
49 # * <tt>mail</tt> - Allows you to specify your email to send.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
50 #
9520166 Mikel Lindsaar Fixed up being able to pass random headers in with headers, or mail. Al...
mikel authored
51 # The hash passed to the mail method allows you to specify any header that a Mail::Message
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
52 # will accept (any valid Email header including optional fields).
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
53 #
54 # The mail method, if not passed a block, will inspect your views and send all the views with
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
55 # the same name as the method, so the above action would send the +welcome.text.plain.erb+ view
56 # file as well as the +welcome.text.html.erb+ view file in a +multipart/alternative+ email.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
57 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
58 # If you want to explicitly render only certain templates, pass a block:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
59 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
60 # mail(:to => user.emai) do |format|
61 # format.text
62 # format.html
63 # end
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
64 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
65 # The block syntax is useful if also need to specify information specific to a part:
66 #
67 # mail(:to => user.emai) do |format|
68 # format.text(:content_transfer_encoding => "base64")
69 # format.html
70 # end
71 #
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
72 # Or even to render a special view:
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
73 #
74 # mail(:to => user.emai) do |format|
75 # format.text
76 # format.html { render "some_other_template" }
77 # end
78 #
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
79 # = Mailer views
80 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
81 # Like Action Controller, each mailer class has a corresponding view directory in which each
82 # method of the class looks for a template with its name.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
83 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
84 # To define a template to be used with a mailing, create an <tt>.erb</tt> file with the same
85 # name as the method in your mailer model. For example, in the mailer defined above, the template at
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
86 # <tt>app/views/notifier/signup_notification.text.plain.erb</tt> would be used to generate the email.
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
87 #
88 # Variables defined in the model are accessible as instance variables in the view.
89 #
90 # Emails by default are sent in plain text, so a sample view for our model example might look like this:
91 #
92 # Hi <%= @account.name %>,
93 # Thanks for joining our service! Please check back often.
94 #
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
95 # You can even use Action Pack helpers in these views. For example:
96 #
97 # You got a new note!
ee70d1b José Valim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
98 # <%= truncate(@note.body, 25) %>
99 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
100 # If you need to access the subject, from or the recipients in the view, you can do that through message object:
ee70d1b José Valim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
101 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
102 # You got a new note from <%= message.from %>!
ee70d1b José Valim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
103 # <%= truncate(@note.body, 25) %>
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
104 #
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
105 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
106 # = Generating URLs
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
107 #
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
108 # URLs can be generated in mailer views using <tt>url_for</tt> or named routes. Unlike controllers from
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
109 # Action Pack, the mailer instance doesn't have any context about the incoming request, so you'll need
110 # to provide all of the details needed to generate a URL.
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
111 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
112 # When using <tt>url_for</tt> you'll need to provide the <tt>:host</tt>, <tt>:controller</tt>, and <tt>:action</tt>:
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
113 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
114 # <%= url_for(:host => "example.com", :controller => "welcome", :action => "greeting") %>
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
115 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
116 # When using named routes you only need to supply the <tt>:host</tt>:
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
117 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
118 # <%= users_url(:host => "example.com") %>
119 #
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
120 # You will want to avoid using the <tt>name_of_route_path</tt> form of named routes because it doesn't
121 # make sense to generate relative URLs in email messages.
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
122 #
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
123 # It is also possible to set a default host that will be used in all mailers by setting the <tt>:host</tt>
124 # option in the <tt>ActionMailer::Base.default_url_options</tt> hash as follows:
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
125 #
126 # ActionMailer::Base.default_url_options[:host] = "example.com"
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
127 #
dc4eec1 Pratik Merge docrails:
lifo authored
128 # This can also be set as a configuration option in <tt>config/environment.rb</tt>:
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
129 #
130 # config.action_mailer.default_url_options = { :host => "example.com" }
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
131 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
132 # If you do decide to set a default <tt>:host</tt> for your mailers you will want to use the
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
133 # <tt>:only_path => false</tt> option when using <tt>url_for</tt>. This will ensure that absolute URLs are
134 # generated because the <tt>url_for</tt> view helper will, by default, generate relative URLs when a
135 # <tt>:host</tt> option isn't explicitly provided.
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
136 #
137 # = Sending mail
138 #
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
139 # Once a mailer action and template are defined, you can deliver your message or create it and save it
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
140 # for delivery later:
141 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
142 # Notifier.welcome(david).deliver # sends the email
143 # mail = Notifier.welcome(david) # => a Mail::Message object
144 # mail.deliver # sends the email
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
145 #
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
146 # You never instantiate your mailer class. Rather, you just call the method you defined on the class itself.
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
147 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
148 # = Multipart Emails
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
149 #
98dc582 Pratik Merge docrails.
lifo authored
150 # Multipart messages can also be used implicitly because Action Mailer will automatically
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
151 # detect and use multipart templates, where each template is named after the name of the action, followed
152 # by the content type. Each such detected template will be added as separate part to the message.
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
153 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
154 # For example, if the following templates existed:
21187c0 David Heinemeier Hansson Apply the rest of Chads patch
dhh authored
155 # * signup_notification.text.plain.erb
156 # * signup_notification.text.html.erb
157 # * signup_notification.text.xml.builder
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
158 # * signup_notification.text.yaml.erb
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
159 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
160 # Each would be rendered and added as a separate part to the message, with the corresponding content
161 # type. The content type for the entire message is automatically set to <tt>multipart/alternative</tt>,
162 # which indicates that the email contains multiple different representations of the same email
163 # body. The same instance variables defined in the action are passed to all email templates.
359caef Jamis Buck A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
164 #
46f30f9 Pratik Merge documentation changes from docrails.
lifo authored
165 # Implicit template rendering is not performed if any attachments or parts have been added to the email.
166 # This means that you'll have to manually add each part to the email and set the content type of the email
167 # to <tt>multipart/alternative</tt>.
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
168 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
169 # = Attachments
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
170 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
171 # You can see above how to make a multipart HTML / Text email, to send attachments is just
172 # as easy:
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
173 #
174 # class ApplicationMailer < ActionMailer::Base
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
175 # def welcome(recipient)
176 # attachments['free_book.pdf'] = { :data => File.read('path/to/file.pdf') }
177 # mail(:to => recipient, :subject => "New account information")
db045db David Heinemeier Hansson Initial
dhh authored
178 # end
3b0e1d9 Joshua Peek Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
179 # end
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
180 #
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
181 # Which will (if it had both a <tt>welcome.text.plain.erb</tt> and <tt>welcome.text.html.erb</tt>
182 # tempalte in the view directory), send a complete <tt>multipart/mixed</tt> email with two parts,
183 # the first part being a <tt>multipart/alternative</tt> with the text and HTML email parts inside,
184 # and the second being a <tt>application/pdf</tt> with a Base64 encoded copy of the file.pdf book
185 # with the filename +free_book.pdf+.
c927aa0 David Heinemeier Hansson Updated documentation
dhh authored
186 #
cefc136 Mikel Lindsaar Adding options to register observers and interceptors through ActionMail...
mikel authored
187 # = Observing and Intercepting Mails
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
188 #
058f7fe Mikel Lindsaar Cleaning up Action Mailer spelling with and without the space
mikel authored
189 # Action Mailer provides hooks into the Mail observer and interceptor methods. These allow you to
cefc136 Mikel Lindsaar Adding options to register observers and interceptors through ActionMail...
mikel authored
190 # register objects that are called during the mail delivery life cycle.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
191 #
cefc136 Mikel Lindsaar Adding options to register observers and interceptors through ActionMail...
mikel authored
192 # An observer object must implement the <tt>:delivered_email(message)</tt> method which will be
193 # called once for every email sent after the email has been sent.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
194 #
cefc136 Mikel Lindsaar Adding options to register observers and interceptors through ActionMail...
mikel authored
195 # An interceptor object must implement the <tt>:delivering_email(message)</tt> method which will be
196 # called before the email is sent, allowing you to make modifications to the email before it hits
197 # the delivery agents. Your object should make and needed modifications directly to the passed
198 # in Mail::Message instance.
20bd4bd David Heinemeier Hansson Updated docs and otherwise
dhh authored
199 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
200 # = Default Hash
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
201 #
058f7fe Mikel Lindsaar Cleaning up Action Mailer spelling with and without the space
mikel authored
202 # Action Mailer provides some intelligent defaults for your emails, these are usually specified in a
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
203 # default method inside the class definition:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
204 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
205 # class Notifier < ActionMailer::Base
206 # default :sender => 'system@example.com'
207 # end
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
208 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
209 # You can pass in any header value that a <tt>Mail::Message</tt>, out of the box, <tt>ActionMailer::Base</tt>
210 # sets the following:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
211 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
212 # * <tt>:mime_version => "1.0"</tt>
213 # * <tt>:charset => "UTF-8",</tt>
214 # * <tt>:content_type => "text/plain",</tt>
215 # * <tt>:parts_order => [ "text/plain", "text/enriched", "text/html" ]</tt>
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
216 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
217 # <tt>parts_order</tt> and <tt>charset</tt> are not actually valid <tt>Mail::Message</tt> header fields,
058f7fe Mikel Lindsaar Cleaning up Action Mailer spelling with and without the space
mikel authored
218 # but Action Mailer translates them appropriately and sets the correct values.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
219 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
220 # As you can pass in any header, you need to either quote the header as a string, or pass it in as
221 # an underscorised symbol, so the following will work:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
222 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
223 # class Notifier < ActionMailer::Base
224 # default 'Content-Transfer-Encoding' => '7bit',
225 # :content_description => 'This is a description'
226 # end
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
227 #
058f7fe Mikel Lindsaar Cleaning up Action Mailer spelling with and without the space
mikel authored
228 # Finally, Action Mailer also supports passing <tt>Proc</tt> objects into the default hash, so you
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
229 # can define methods that evaluate as the message is being generated:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
230 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
231 # class Notifier < ActionMailer::Base
232 # default 'X-Special-Header' => Proc.new { my_method }
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
233 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
234 # private
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
235 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
236 # def my_method
237 # 'some complex call'
238 # end
239 # end
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
240 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
241 # Note that the proc is evaluated right at the start of the mail message generation, so if you
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
242 # set something in the defaults using a proc, and then set the same thing inside of your
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
243 # mailer method, it will get over written by the mailer method.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
244 #
c927aa0 David Heinemeier Hansson Updated documentation
dhh authored
245 # = Configuration options
246 #
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
247 # These options are specified on the class level, like
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
248 # <tt>ActionMailer::Base.template_root = "/my/templates"</tt>
c927aa0 David Heinemeier Hansson Updated documentation
dhh authored
249 #
fb30feb Mikel Lindsaar Adding more docs to ActionMailer
mikel authored
250 # * <tt>default</tt> - You can pass this in at a class level as well as within the class itself as
251 # per the above section.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
252 #
c927aa0 David Heinemeier Hansson Updated documentation
dhh authored
253 # * <tt>logger</tt> - the logger is used for generating information on the mailing run if available.
254 # Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers.
255 #
64092de Xavier Noria Improve documentation coverage and markup
fxn authored
256 # * <tt>smtp_settings</tt> - Allows detailed configuration for <tt>:smtp</tt> delivery method:
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
257 # * <tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default
258 # "localhost" setting.
dc4eec1 Pratik Merge docrails:
lifo authored
259 # * <tt>:port</tt> - On the off chance that your mail server doesn't run on port 25, you can change it.
260 # * <tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.
261 # * <tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.
262 # * <tt>:password</tt> - If your mail server requires authentication, set the password in this setting.
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
263 # * <tt>:authentication</tt> - If your mail server requires authentication, you need to specify the
264 # authentication type here.
46f30f9 Pratik Merge documentation changes from docrails.
lifo authored
265 # This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>.
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
266 # * <tt>:enable_starttls_auto</tt> - When set to true, detects if STARTTLS is enabled in your SMTP server
267 # and starts to use it.
c927aa0 David Heinemeier Hansson Updated documentation
dhh authored
268 #
46f30f9 Pratik Merge documentation changes from docrails.
lifo authored
269 # * <tt>sendmail_settings</tt> - Allows you to override options for the <tt>:sendmail</tt> delivery method.
270 # * <tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
271 # * <tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i -t</tt> with <tt>-f sender@addres</tt>
272 # added automatically before the message is sent.
dc4eec1 Pratik Merge docrails:
lifo authored
273 #
fbe6c3c Eric Davis Adds a :file delivery_method to save email to a file on disk
edavis10 authored
274 # * <tt>file_settings</tt> - Allows you to override options for the <tt>:file</tt> delivery method.
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
275 # * <tt>:location</tt> - The directory into which emails will be written. Defaults to the application
276 # <tt>tmp/mails</tt>.
fbe6c3c Eric Davis Adds a :file delivery_method to save email to a file on disk
edavis10 authored
277 #
dc4eec1 Pratik Merge docrails:
lifo authored
278 # * <tt>raise_delivery_errors</tt> - Whether or not errors should be raised if the email fails to be delivered.
c927aa0 David Heinemeier Hansson Updated documentation
dhh authored
279 #
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
280 # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are <tt>:smtp</tt> (default),
281 # <tt>:sendmail</tt>, <tt>:test</tt>, and <tt>:file</tt>. Or you may provide a custom delivery method
282 # object eg. MyOwnDeliveryMethodClass.new. See the Mail gem documentation on the interface you need to
283 # implement for a custom delivery agent.
c927aa0 David Heinemeier Hansson Updated documentation
dhh authored
284 #
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
285 # * <tt>perform_deliveries</tt> - Determines whether emails are actually sent from Action Mailer when you
286 # call <tt>.deliver</tt> on an mail message or on an Action Mailer method. This is on by default but can
287 # be turned off to aid in functional testing.
c927aa0 David Heinemeier Hansson Updated documentation
dhh authored
288 #
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
289 # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with
290 # <tt>delivery_method :test</tt>. Most useful for unit and functional testing.
af56c80 David Heinemeier Hansson Updated documentation
dhh authored
291 #
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
292 # * <tt>default_charset</tt> - This is now deprecated, use the +default+ method above to
21dcc20 Mikel Lindsaar Fixed up documentation to reflect code change and cleaned up tests of sp...
mikel authored
293 # set the default +:charset+.
c2e7851 José Valim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
294 #
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
295 # * <tt>default_content_type</tt> - This is now deprecated, use the +default+ method above
21dcc20 Mikel Lindsaar Fixed up documentation to reflect code change and cleaned up tests of sp...
mikel authored
296 # to set the default +:content_type+.
c2e7851 José Valim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
297 #
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
298 # * <tt>default_mime_version</tt> - This is now deprecated, use the +default+ method above
21dcc20 Mikel Lindsaar Fixed up documentation to reflect code change and cleaned up tests of sp...
mikel authored
299 # to set the default +:mime_version+.
c2e7851 José Valim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
300 #
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
301 # * <tt>default_implicit_parts_order</tt> - This is now deprecated, use the +default+ method above
21dcc20 Mikel Lindsaar Fixed up documentation to reflect code change and cleaned up tests of sp...
mikel authored
302 # to set the default +:parts_order+. Parts Order is used when a message is built implicitly
303 # (i.e. multiple parts are assembled from templates which specify the content type in their
304 # filenames) this variable controls how the parts are ordered.
4964d3b José Valim Make ActionMailer::Base inherit from AbstractController::Base
josevalim authored
305 class Base < AbstractController::Base
dbcf01e Mikel Lindsaar Removing quoting.rb, upgrade to 2.1.3.6, changing all utf-8 references t...
mikel authored
306 include DeliveryMethods
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
307 abstract!
308
c03c40b José Valim Expose a _render_partial hook as thhe _render_template one and make use ...
josevalim authored
309 include AbstractController::Logger
83f4d86 David Heinemeier Hansson Rename the RenderingController module to just plain Rendering
dhh authored
310 include AbstractController::Rendering
a9751a7 José Valim Refactor ActionMailer layout and remove legacy one.
josevalim authored
311 include AbstractController::Layouts
684c2dc José Valim Remove ActionMailer helpers and rely on AbstractController one.
josevalim authored
312 include AbstractController::Helpers
48a3985 José Valim Also include translation in ActionMailer.
josevalim authored
313 include AbstractController::Translation
08baa34 David Heinemeier Hansson Extract assets paths and make them available to Action Mailer as well
dhh authored
314 include AbstractController::AssetPaths
359caef Jamis Buck A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
315
ee70d1b José Valim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
316 helper ActionMailer::MailHelper
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
317
5dead5b Maintain old_api and deprecated_api in different files.
José Valim and Mikel Lindsaar authored
318 include ActionMailer::OldApi
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
319 include ActionMailer::DeprecatedApi
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
320
cefc136 Mikel Lindsaar Adding options to register observers and interceptors through ActionMail...
mikel authored
321 delegate :register_observer, :to => Mail
322 delegate :register_interceptor, :to => Mail
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
323
c927aa0 David Heinemeier Hansson Updated documentation
dhh authored
324 private_class_method :new #:nodoc:
db045db David Heinemeier Hansson Initial
dhh authored
325
e5ab4b0 Jeremy Kemper Convert to class_attribute
jeremy authored
326 class_attribute :default_params
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
327 self.default_params = {
328 :mime_version => "1.0",
dbcf01e Mikel Lindsaar Removing quoting.rb, upgrade to 2.1.3.6, changing all utf-8 references t...
mikel authored
329 :charset => "UTF-8",
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
330 :content_type => "text/plain",
331 :parts_order => [ "text/plain", "text/enriched", "text/html" ]
e5ab4b0 Jeremy Kemper Convert to class_attribute
jeremy authored
332 }.freeze
e1c1318 Added delivers_from.
José Valim and Mikel Lindsaar authored
333
eda1719 Jamis Buck ActionMailer::Base.deliver(email) had been accidentally removed, but was...
jamis authored
334 class << self
0b05acd Mikel Lindsaar Implementing class level :defaults hash, instead of delivers_from et al
mikel authored
335
bd5ed65 risk danger olson Update ActionMailer so it treats ActionView the same way that ActionCont...
technoweenie authored
336 def mailer_name
337 @mailer_name ||= name.underscore
338 end
0750304 Mikel Lindsaar Migrated over to Mail doing delivery.
mikel authored
339 attr_writer :mailer_name
340 alias :controller_path :mailer_name
81c416b José Valim More refactoring on ActionMailer::Base.
josevalim authored
341
e5ab4b0 Jeremy Kemper Convert to class_attribute
jeremy authored
342 def default(value = nil)
343 self.default_params = default_params.merge(value).freeze if value
344 default_params
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
345 end
346
59f1df1 Jamis Buck Update/extend ActionMailer documentation (rdoc)
jamis authored
347 # Receives a raw email, parses it into an email object, decodes it,
348 # instantiates a new mailer, and passes the email object to the mailer
98dc582 Pratik Merge docrails.
lifo authored
349 # object's +receive+ method. If you want your mailer to be able to
350 # process incoming messages, you'll need to implement a +receive+
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
351 # method that accepts the raw email string as a parameter:
59f1df1 Jamis Buck Update/extend ActionMailer documentation (rdoc)
jamis authored
352 #
353 # class MyMailer < ActionMailer::Base
354 # def receive(mail)
355 # ...
356 # end
357 # end
704daad José Valim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
358 def receive(raw_mail)
731d439 Justin George Change event namespace ordering to most-significant first [#4504 state:r...
jaggederest authored
359 ActiveSupport::Notifications.instrument("receive.action_mailer") do |payload|
704daad José Valim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
360 mail = Mail.new(raw_mail)
361 set_payload_for_mail(payload, mail)
2a6bc12 José Valim Add subscriber to ActionMailer.
josevalim authored
362 new.receive(mail)
363 end
eda1719 Jamis Buck ActionMailer::Base.deliver(email) had been accidentally removed, but was...
jamis authored
364 end
365
bb2c7b4 Mikel Lindsaar Updating Action Mailer documentation
mikel authored
366 # Wraps an email delivery inside of Active Support Notifications instrumentation. This
367 # method is actually called by the <tt>Mail::Message</tt> object itself through a call back
368 # when you call <tt>:deliver</tt> on the Mail::Message, calling +deliver_mail+ directly
369 # and passing a Mail::Message will do nothing except tell the logger you sent the email.
e4a989e Added delivery_handler method to mail and implemented in ActionMailer to...
José Valim and Mikel Lindsaar authored
370 def deliver_mail(mail) #:nodoc:
731d439 Justin George Change event namespace ordering to most-significant first [#4504 state:r...
jaggederest authored
371 ActiveSupport::Notifications.instrument("deliver.action_mailer") do |payload|
258ca14 Delegated ActionMailer::Base.deliveries to Mail.deliveries, added callba...
José Valim and Mikel Lindsaar authored
372 self.set_payload_for_mail(payload, mail)
ace7497 Got AM working with Mail yield on delivery_handler and updated tests
José Valim and Mikel Lindsaar authored
373 yield # Let Mail do the delivery actions
258ca14 Delegated ActionMailer::Base.deliveries to Mail.deliveries, added callba...
José Valim and Mikel Lindsaar authored
374 end
375 end
376
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
377 def respond_to?(method, *args) #:nodoc:
378 super || action_methods.include?(method.to_s)
379 end
380
381 protected
382
704daad José Valim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
383 def set_payload_for_mail(payload, mail) #:nodoc:
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
384 payload[:mailer] = self.name
c905fce José Valim Add message_id to AM payload and don't send bcc and cc if they were not ...
josevalim authored
385 payload[:message_id] = mail.message_id
386 payload[:subject] = mail.subject
387 payload[:to] = mail.to
388 payload[:from] = mail.from
389 payload[:bcc] = mail.bcc if mail.bcc.present?
390 payload[:cc] = mail.cc if mail.cc.present?
391 payload[:date] = mail.date
392 payload[:mail] = mail.encoded
704daad José Valim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
393 end
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
394
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
395 def method_missing(method, *args) #:nodoc:
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
396 if action_methods.include?(method.to_s)
397 new(method, *args).message
398 else
399 super
400 end
401 end
eda1719 Jamis Buck ActionMailer::Base.deliver(email) had been accidentally removed, but was...
jamis authored
402 end
403
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
404 attr_internal :message
405
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
406 # Instantiate a new mailer object. If +method_name+ is not +nil+, the mailer
407 # will be initialized according to the named method. If not, the mailer will
408 # remain uninitialized (useful when you only need to invoke the "receive"
409 # method, for instance).
410 def initialize(method_name=nil, *args)
411 super()
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
412 @_message = Mail.new
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
413 process(method_name, *args) if method_name
414 end
415
3fc609e José Valim Fix ActionMailer test broken in 99d54599215c2a8cea7e57f609e8e578043d71b2
josevalim authored
416 def process(*args) #:nodoc:
417 lookup_context.skip_default_locale!
418 super
419 end
420
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
421 # Allows you to pass random and unusual headers to the new +Mail::Message+ object
422 # which will add them to itself.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
423 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
424 # headers['X-Special-Domain-Specific-Header'] = "SecretValue"
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
425 #
9520166 Mikel Lindsaar Fixed up being able to pass random headers in with headers, or mail. Al...
mikel authored
426 # You can also pass a hash into headers of header field names and values, which
427 # will then be set on the Mail::Message object:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
428 #
05c4ad9 Tidy up tests and docs.
José Valim and Mikel Lindsaar authored
429 # headers 'X-Special-Domain-Specific-Header' => "SecretValue",
430 # 'In-Reply-To' => incoming.message_id
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
431 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
432 # The resulting Mail::Message will have the following in it's header:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
433 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
434 # X-Special-Domain-Specific-Header: SecretValue
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
435 def headers(args=nil)
436 if args
9520166 Mikel Lindsaar Fixed up being able to pass random headers in with headers, or mail. Al...
mikel authored
437 @_message.headers(args)
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
438 else
439 @_message
440 end
441 end
c34cfcc Mikel Lindsaar Created mail method for new API
mikel authored
442
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
443 # Allows you to add attachments to an email, like so:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
444 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
445 # mail.attachments['filename.jpg'] = File.read('/path/to/filename.jpg')
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
446 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
447 # If you do this, then Mail will take the file name and work out the mime type
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
448 # set the Content-Type, Content-Disposition, Content-Transfer-Encoding and
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
449 # base64 encode the contents of the attachment all for you.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
450 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
451 # You can also specify overrides if you want by passing a hash instead of a string:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
452 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
453 # mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
454 # :content => File.read('/path/to/filename.jpg')}
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
455 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
456 # If you want to use a different encoding than Base64, you can pass an encoding in,
457 # but then it is up to you to pass in the content pre-encoded, and don't expect
458 # Mail to know how to decode this data:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
459 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
460 # file_content = SpecialEncode(File.read('/path/to/filename.jpg'))
461 # mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
462 # :encoding => 'SpecialEncoding',
463 # :content => file_content }
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
464 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
465 # You can also search for specific attachments:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
466 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
467 # # By Filename
468 # mail.attachments['filename.jpg'] #=> Mail::Part object or nil
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
469 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
470 # # or by index
471 # mail.attachments[0] #=> Mail::Part (first attachment)
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
472 #
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
473 def attachments
474 @_message.attachments
475 end
dcb9253 Add basic template rendering to new DSL.
José Valim and Mikel Lindsaar authored
476
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
477 # The main method that creates the message and renders the email templates. There are
478 # two ways to call this method, with a block, or without a block.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
479 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
480 # Both methods accept a headers hash. This hash allows you to specify the most used headers
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
481 # in an email message, these are:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
482 #
058f7fe Mikel Lindsaar Cleaning up Action Mailer spelling with and without the space
mikel authored
483 # * <tt>:subject</tt> - The subject of the message, if this is omitted, Action Mailer will
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
484 # ask the Rails I18n class for a translated <tt>:subject</tt> in the scope of
485 # <tt>[:actionmailer, mailer_scope, action_name]</tt> or if this is missing, will translate the
486 # humanized version of the <tt>action_name</tt>
487 # * <tt>:to</tt> - Who the message is destined for, can be a string of addresses, or an array
488 # of addresses.
0b05acd Mikel Lindsaar Implementing class level :defaults hash, instead of delivers_from et al
mikel authored
489 # * <tt>:from</tt> - Who the message is from
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
490 # * <tt>:cc</tt> - Who you would like to Carbon-Copy on this email, can be a string of addresses,
491 # or an array of addresses.
492 # * <tt>:bcc</tt> - Who you would like to Blind-Carbon-Copy on this email, can be a string of
493 # addresses, or an array of addresses.
494 # * <tt>:reply_to</tt> - Who to set the Reply-To header of the email to.
495 # * <tt>:date</tt> - The date to say the email was sent on.
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
496 #
497 # You can set default values for any of the above headers (except :date) by using the <tt>default</tt>
0b05acd Mikel Lindsaar Implementing class level :defaults hash, instead of delivers_from et al
mikel authored
498 # class method:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
499 #
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
500 # class Notifier < ActionMailer::Base
452bb1e Jeremy Kemper Rename 'defaults' class method to 'default' to reflect that it's a decla...
jeremy authored
501 # self.default :from => 'no-reply@test.lindsaar.net',
502 # :bcc => 'email_logger@test.lindsaar.net',
503 # :reply_to => 'bounces@test.lindsaar.net'
0b05acd Mikel Lindsaar Implementing class level :defaults hash, instead of delivers_from et al
mikel authored
504 # end
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
505 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
506 # If you need other headers not listed above, use the <tt>headers['name'] = value</tt> method.
507 #
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
508 # When a <tt>:return_path</tt> is specified as header, that value will be used as the 'envelope from'
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
509 # address for the Mail message. Setting this is useful when you want delivery notifications
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
510 # sent to a different address than the one in <tt>:from</tt>. Mail will actually use the
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
511 # <tt>:return_path</tt> in preference to the <tt>:sender</tt> in preference to the <tt>:from</tt>
512 # field for the 'envelope from' value.
513 #
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
514 # If you do not pass a block to the +mail+ method, it will find all templates in the
be35a15 José Valim Allow to choose the template path and template name used in implicit ren...
josevalim authored
515 # view paths using by default the mailer name and the method name that it is being
516 # called from, it will then create parts for each of these templates intelligently,
517 # making educated guesses on correct content type and sequence, and return a fully
518 # prepared Mail::Message ready to call <tt>:deliver</tt> on to send.
519 #
520 # For example:
521 #
522 # class Notifier < ActionMailer::Base
523 # default :from => 'no-reply@test.lindsaar.net',
524 #
525 # def welcome
526 # mail(:to => 'mikel@test.lindsaar.net')
527 # end
528 # end
529 #
530 # Will look for all templates at "app/views/notifier" with name "welcome". However, those
531 # can be customized:
532 #
533 # mail(:template_path => 'notifications', :template_name => 'another')
534 #
535 # And now it will look for all templates at "app/views/notifications" with name "another".
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
536 #
537 # If you do pass a block, you can render specific templates of your choice:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
538 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
539 # mail(:to => 'mikel@test.lindsaar.net') do |format|
540 # format.text
541 # format.html
542 # end
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
543 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
544 # You can even render text directly without using a template:
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
545 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
546 # mail(:to => 'mikel@test.lindsaar.net') do |format|
547 # format.text { render :text => "Hello Mikel!" }
548 # format.html { render :text => "<h1>Hello Mikel!</h1>" }
549 # end
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
550 #
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
551 # Which will render a <tt>multipart/alternative</tt> email with <tt>text/plain</tt> and
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
552 # <tt>text/html</tt> parts.
6589976 Remove old files, add some information to docs and improve test suite.
José Valim and Mikel Lindsaar authored
553 #
554 # The block syntax also allows you to customize the part headers if desired:
555 #
556 # mail(:to => 'mikel@test.lindsaar.net') do |format|
557 # format.text(:content_transfer_encoding => "base64")
558 # format.html
559 # end
560 #
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
561 def mail(headers={}, &block)
562 # Guard flag to prevent both the old and the new API from firing
563 # Should be removed when old API is removed
564 @mail_was_called = true
565 m = @_message
258ca14 Delegated ActionMailer::Base.deliveries to Mail.deliveries, added callba...
José Valim and Mikel Lindsaar authored
566
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
567 # At the beginning, do not consider class default for parts order neither content_type
568 content_type = headers[:content_type]
569 parts_order = headers[:parts_order]
1cd5592 First work on implicit multipart.
José Valim and Mikel Lindsaar authored
570
08b07b6 Mikel Lindsaar Adding ability to pass proc's to the ActionMailer class default method
mikel authored
571 # Call all the procs (if any)
572 default_values = self.class.default.merge(self.class.default) do |k,v|
ceaa100 Mikel Lindsaar Adding ability for the procs to be called within the instance, allows yo...
mikel authored
573 v.respond_to?(:call) ? v.bind(self).call : v
08b07b6 Mikel Lindsaar Adding ability to pass proc's to the ActionMailer class default method
mikel authored
574 end
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
575
b5f9a9f José Valim Move set_fields! to the old API module.
josevalim authored
576 # Handle defaults
08b07b6 Mikel Lindsaar Adding ability to pass proc's to the ActionMailer class default method
mikel authored
577 headers = headers.reverse_merge(default_values)
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
578 headers[:subject] ||= default_i18n_subject
b5f9a9f José Valim Move set_fields! to the old API module.
josevalim authored
579
580 # Apply charset at the beginning so all fields are properly quoted
581 m.charset = charset = headers[:charset]
582
583 # Set configure delivery behavior
584 wrap_delivery_behavior!(headers.delete(:delivery_method))
585
586 # Assign all headers except parts_order, content_type and body
b4fd5e6 José Valim template_name and template_path should not be added to mail headers.
josevalim authored
587 assignable = headers.except(:parts_order, :content_type, :body, :template_name, :template_path)
b5f9a9f José Valim Move set_fields! to the old API module.
josevalim authored
588 assignable.each { |k, v| m[k] = v }
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
589
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
590 # Render the templates and blocks
39a1b06 Deprecate old defaults API.
José Valim and Mikel Lindsaar authored
591 responses, explicit_order = collect_responses_and_parts_order(headers, &block)
b5f9a9f José Valim Move set_fields! to the old API module.
josevalim authored
592 create_parts_from_responses(m, responses)
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
593
b5f9a9f José Valim Move set_fields! to the old API module.
josevalim authored
594 # Setup content type, reapply charset and handle parts order
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
595 m.content_type = set_content_type(m, content_type, headers[:content_type])
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
596 m.charset = charset
597
e7e4ed4 Set sort order for explicit parts from the collector's template sequence
José Valim and Mikel Lindsaar authored
598 if m.multipart?
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
599 parts_order ||= explicit_order || headers[:parts_order]
600 m.body.set_sort_order(parts_order)
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
601 m.body.sort_parts!
602 end
bb9d71f Move class methods to deprecated stuff.
José Valim and Mikel Lindsaar authored
603
c34cfcc Mikel Lindsaar Created mail method for new API
mikel authored
604 m
605 end
606
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
607 protected
608
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
609 def set_content_type(m, user_content_type, class_default)
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
610 params = m.content_type_parameters || {}
611 case
612 when user_content_type.present?
613 user_content_type
614 when m.has_attachments?
311d99e Mikel Lindsaar Adding inline attachment support to ActionMailer
mikel authored
615 if m.attachments.detect { |a| a.inline? }
616 ["multipart", "related", params]
617 else
618 ["multipart", "mixed", params]
619 end
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
620 when m.multipart?
621 ["multipart", "alternative", params]
622 else
b6b3db6 Mikel Lindsaar Fixed bug on HTML only emails getting set to text/plain
mikel authored
623 m.content_type || class_default
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
624 end
625 end
626
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
627 def default_i18n_subject #:nodoc:
5c3ef8c Refactor subject with i18n.
José Valim and Mikel Lindsaar authored
628 mailer_scope = self.class.mailer_name.gsub('/', '.')
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
629 I18n.t(:subject, :scope => [:actionmailer, mailer_scope, action_name], :default => action_name.humanize)
5c3ef8c Refactor subject with i18n.
José Valim and Mikel Lindsaar authored
630 end
631
39a1b06 Deprecate old defaults API.
José Valim and Mikel Lindsaar authored
632 def collect_responses_and_parts_order(headers) #:nodoc:
633 responses, parts_order = [], nil
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
634
635 if block_given?
a09e992 José Valim Ensure details are frozen after @details_keys lookup. The implementation...
josevalim authored
636 collector = ActionMailer::Collector.new(lookup_context) { render(action_name) }
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
637 yield(collector)
39a1b06 Deprecate old defaults API.
José Valim and Mikel Lindsaar authored
638 parts_order = collector.responses.map { |r| r[:content_type] }
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
639 responses = collector.responses
640 elsif headers[:body]
641 responses << {
be35a15 José Valim Allow to choose the template path and template name used in implicit ren...
josevalim authored
642 :body => headers.delete(:body),
452bb1e Jeremy Kemper Rename 'defaults' class method to 'default' to reflect that it's a decla...
jeremy authored
643 :content_type => self.class.default[:content_type] || "text/plain"
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
644 }
645 else
be35a15 José Valim Allow to choose the template path and template name used in implicit ren...
josevalim authored
646 templates_path = headers.delete(:template_path) || self.class.mailer_name
647 templates_name = headers.delete(:template_name) || action_name
648
649 each_template(templates_path, templates_name) do |template|
f28d856 José Valim Improve performance of the rendering stack by freezing formats as a sign...
josevalim authored
650 self.formats = template.formats
651
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
652 responses << {
2a12686 José Valim Allow anything that responds to render to be given as :template and use ...
josevalim authored
653 :body => render(:template => template),
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
654 :content_type => template.mime_type.to_s
655 }
656 end
657 end
658
39a1b06 Deprecate old defaults API.
José Valim and Mikel Lindsaar authored
659 [responses, parts_order]
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
660 end
661
be35a15 José Valim Allow to choose the template path and template name used in implicit ren...
josevalim authored
662 def each_template(paths, name, &block) #:nodoc:
41af6d9 Jeremy Kemper Use Array.wrap not Array()
jeremy authored
663 Array.wrap(paths).each do |path|
36eb1a6 José Valim Bring AM up to date with new rendering stack.
josevalim authored
664 templates = lookup_context.find_all(name, path)
00d6271 José Valim Clean up the API required from ActionView::Template.
josevalim authored
665 templates = templates.uniq_by { |t| t.formats }
0ece244 Ensure implicit multipart templates with locale works as expected.
José Valim and Mikel Lindsaar authored
666
36eb1a6 José Valim Bring AM up to date with new rendering stack.
josevalim authored
667 unless templates.empty?
668 templates.each(&block)
669 return
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
670 end
671 end
672 end
673
b5f9a9f José Valim Move set_fields! to the old API module.
josevalim authored
674 def create_parts_from_responses(m, responses) #:nodoc:
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
675 if responses.size == 1 && !m.has_attachments?
9dd65c3 Make defaults accept a hash.
José Valim and Mikel Lindsaar authored
676 responses[0].each { |k,v| m[k] = v }
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
677 elsif responses.size > 1 && m.has_attachments?
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
678 container = Mail::Part.new
74a5889 Refactor content type setting, added tests to ensure boundary exists on ...
José Valim and Mikel Lindsaar authored
679 container.content_type = "multipart/alternative"
b5f9a9f José Valim Move set_fields! to the old API module.
josevalim authored
680 responses.each { |r| insert_part(container, r, m.charset) }
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
681 m.add_part(container)
682 else
b5f9a9f José Valim Move set_fields! to the old API module.
josevalim authored
683 responses.each { |r| insert_part(m, r, m.charset) }
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
684 end
359caef Jamis Buck A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
685 end
686
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
687 def insert_part(container, response, charset) #:nodoc:
688 response[:charset] ||= charset
689 part = Mail::Part.new(response)
690 container.add_part(part)
359caef Jamis Buck A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
691 end
3fad0cd David Heinemeier Hansson Added support for charsets for both subject and body. The default charse...
dhh authored
692
458f571 Yehuda Katz Remove the need for a special action_mailer.url_for initializer that loa...
wycats authored
693 module DeprecatedUrlOptions
694 def default_url_options
695 deprecated_url_options
696 end
697
698 def default_url_options=(val)
699 deprecated_url_options
700 end
701
702 def deprecated_url_options
703 raise "You can no longer call ActionMailer::Base.default_url_options " \
704 "directly. You need to set config.action_mailer.default_url_options. " \
705 "If you are using ActionMailer standalone, you need to include the " \
706 "url_helpers of a router directly."
707 end
708 end
709
710 # This module will complain if the user tries to set default_url_options
711 # directly instead of through the config object. In ActionMailer's Railtie,
712 # we include the url_helpers of the router, which will override this module
713 extend DeprecatedUrlOptions
714
ef5dada Natalie Weizenbaum Only run load hooks once a file has been fully loaded.
nex3 authored
715 ActiveSupport.run_load_hooks(:action_mailer, self)
db045db David Heinemeier Hansson Initial
dhh authored
716 end
717 end
Something went wrong with that request. Please try again.