Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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