Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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