Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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