Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 567 lines (523 sloc) 25.512 kb
a9751a7 @josevalim Refactor ActionMailer layout and remove legacy one.
josevalim authored
1 require 'active_support/core_ext/class'
0ece244 Ensure implicit multipart templates with locale works as expected.
José Valim and Mikel Lindsaar authored
2 require 'active_support/core_ext/object/blank'
3 require 'active_support/core_ext/array/uniq_by'
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
4 require 'active_support/core_ext/module/delegation'
0ece244 Ensure implicit multipart templates with locale works as expected.
José Valim and Mikel Lindsaar authored
5 require 'active_support/core_ext/string/inflections'
616ebb8 @josevalim Remove unused code paths and require mail only when it's needed.
josevalim authored
6 require 'mail'
a288082 @mikel Adding :transfer_encoding -> :content_transfer_encoding as part of Tmail...
mikel authored
7 require 'action_mailer/tmail_compat'
c985a0e Add some tests to collector with templates and any.
José Valim and Mikel Lindsaar authored
8 require 'action_mailer/collector'
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 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
17 # $ script/generate mailer Notifier
18 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
19 # The generated model inherits from ActionMailer::Base. Emails are defined by creating methods
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
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
26 # delivers_from 'system@example.com'
27 #
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 # :subject => "New account information" }
33 # end
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
34 # end
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
35 #
36 # Within the mailer method, you have access to the following methods:
37 #
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>
40 # * <tt>headers[]=</tt> - Allows you to specify non standard headers in your email such
41 # as <tt>headers['X-No-Spam'] = 'True'</tt>
42 # * <tt>mail</tt> - Allows you to specify your email to send.
43 #
44 # The hash passed to the mail method allows you to specify the most used headers in an email
45 # message, such as <tt>Subject</tt>, <tt>To</tt>, <tt>From</tt>, <tt>Cc</tt>, <tt>Bcc</tt>,
46 # <tt>Reply-To</tt> and <tt>Date</tt>. See the <tt>ActionMailer#mail</tt> method for more details.
47 #
48 # If you need other headers not listed above, use the <tt>headers['name'] = value</tt> method.
49 #
50 # The mail method, if not passed a block, will inspect your views and send all the views with
51 # the same name as the method, so the above action would send the +welcome.plain.erb+ view file
52 # as well as the +welcome.html.erb+ view file in a +multipart/alternate+ email.
53 #
54 # If you want to explicitly render only certain templates, pass a block:
55 #
56 # mail(:to => user.emai) do |format|
57 # format.text
58 # format.enriched, {:content_type => 'text/rtf'}
59 # format.html
60 # end
20bd4bd @dhh Updated docs and otherwise
dhh authored
61 #
62 # = Mailer views
63 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
64 # Like Action Controller, each mailer class has a corresponding view directory in which each
65 # method of the class looks for a template with its name.
66 #
67 # To define a template to be used with a mailing, create an <tt>.erb</tt> file with the same
68 # name as the method in your mailer model. For example, in the mailer defined above, the template at
69 # <tt>app/views/notifier/signup_notification.text.erb</tt> would be used to generate the email.
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
70 #
71 # Variables defined in the model are accessible as instance variables in the view.
72 #
73 # Emails by default are sent in plain text, so a sample view for our model example might look like this:
74 #
75 # Hi <%= @account.name %>,
76 # Thanks for joining our service! Please check back often.
77 #
20bd4bd @dhh Updated docs and otherwise
dhh authored
78 # You can even use Action Pack helpers in these views. For example:
79 #
80 # You got a new note!
ee70d1b @josevalim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
81 # <%= truncate(@note.body, 25) %>
82 #
83 # If you need to access the subject, from or the recipients in the view, you can do that through mailer object:
84 #
85 # You got a new note from <%= mailer.from %>!
86 # <%= truncate(@note.body, 25) %>
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
87 #
20bd4bd @dhh Updated docs and otherwise
dhh authored
88 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
89 # = Generating URLs
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
90 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
91 # URLs can be generated in mailer views using <tt>url_for</tt> or named routes.
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
92 # Unlike controllers from Action Pack, the mailer instance doesn't have any context about the incoming request,
93 # so you'll need to provide all of the details needed to generate a URL.
20bd4bd @dhh Updated docs and otherwise
dhh authored
94 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
95 # 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
96 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
97 # <%= url_for(:host => "example.com", :controller => "welcome", :action => "greeting") %>
20bd4bd @dhh Updated docs and otherwise
dhh authored
98 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
99 # 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
100 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
101 # <%= users_url(:host => "example.com") %>
102 #
103 # You will want to avoid using the <tt>name_of_route_path</tt> form of named routes because it doesn't make sense to
104 # generate relative URLs in email messages.
105 #
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
106 # It is also possible to set a default host that will be used in all mailers by setting the <tt>:host</tt> option in
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
107 # the <tt>ActionMailer::Base.default_url_options</tt> hash as follows:
108 #
109 # ActionMailer::Base.default_url_options[:host] = "example.com"
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
110 #
dc4eec1 @lifo Merge docrails:
lifo authored
111 # This can also be set as a configuration option in <tt>config/environment.rb</tt>:
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
112 #
113 # config.action_mailer.default_url_options = { :host => "example.com" }
20bd4bd @dhh Updated docs and otherwise
dhh authored
114 #
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
115 # If you do decide to set a default <tt>:host</tt> for your mailers you will want to use the
116 # <tt>:only_path => false</tt> option when using <tt>url_for</tt>. This will ensure that absolute URLs are generated because
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
117 # the <tt>url_for</tt> view helper will, by default, generate relative URLs when a <tt>:host</tt> option isn't
4809dcc * Remove default_url_options from mailer generator
Cody Fauser authored
118 # explicitly provided.
20bd4bd @dhh Updated docs and otherwise
dhh authored
119 #
120 # = Sending mail
121 #
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
122 # 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
123 # for delivery later:
124 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
125 # Notifier.welcome(david).deliver # sends the email
126 # mail = Notifier.welcome(david) # => a Mail::Message object
127 # mail.deliver # sends the email
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
128 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
129 # You never instantiate your mailer class. Rather, you just call the method on the class itself.
20bd4bd @dhh Updated docs and otherwise
dhh authored
130 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
131 # = Multipart Emails
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
132 #
98dc582 @lifo Merge docrails.
lifo authored
133 # 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
134 # detect and use multipart templates, where each template is named after the name of the action, followed
135 # 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
136 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
137 # For example, if the following templates existed:
21187c0 @dhh Apply the rest of Chads patch
dhh authored
138 # * signup_notification.text.plain.erb
139 # * signup_notification.text.html.erb
140 # * signup_notification.text.xml.builder
141 # * signup_notification.text.x-yaml.erb
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
142 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
143 # Each would be rendered and added as a separate part to the message, with the corresponding content
144 # type. The content type for the entire message is automatically set to <tt>multipart/alternative</tt>,
145 # which indicates that the email contains multiple different representations of the same email
146 # 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
147 #
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
148 # Implicit template rendering is not performed if any attachments or parts have been added to the email.
149 # This means that you'll have to manually add each part to the email and set the content type of the email
150 # to <tt>multipart/alternative</tt>.
20bd4bd @dhh Updated docs and otherwise
dhh authored
151 #
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
152 # = Attachments
20bd4bd @dhh Updated docs and otherwise
dhh authored
153 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
154 # You can see above how to make a multipart HTML / Text email, to send attachments is just
155 # as easy:
0a407bc ActionMailer::Base documentation rewrite. Closes #4991 [Kevin Clark, Mar...
Marcel Molina authored
156 #
157 # class ApplicationMailer < ActionMailer::Base
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
158 # def welcome(recipient)
159 # attachments['free_book.pdf'] = { :data => File.read('path/to/file.pdf') }
160 # mail(:to => recipient, :subject => "New account information")
db045db @dhh Initial
dhh authored
161 # end
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
162 # end
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
163 #
164 # Which will (if it had both a <tt>.text.erb</tt> and <tt>.html.erb</tt> tempalte in the view
165 # directory), send a complete <tt>multipart/mixed</tt> email with two parts, the first part being
166 # a <tt>multipart/alternate</tt> with the text and HTML email parts inside, and the second being
167 # a <tt>application/pdf</tt> with a Base64 encoded copy of the file.pdf book with the filename
168 # +free_book.pdf+.
c927aa0 @dhh Updated documentation
dhh authored
169 #
20bd4bd @dhh Updated docs and otherwise
dhh authored
170 #
c927aa0 @dhh Updated documentation
dhh authored
171 # = Configuration options
172 #
173 # These options are specified on the class level, like <tt>ActionMailer::Base.template_root = "/my/templates"</tt>
174 #
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
175 # * <tt>delivers_from</tt> - Pass this the address that then defaults as the +from+ address on all the
176 # emails sent. Can be overridden on a per mail basis by passing <tt>:from => 'another@address'</tt> in
177 # the +mail+ method.
178 #
64092de @fxn Improve documentation coverage and markup
fxn authored
179 # * <tt>template_root</tt> - Determines the base from which template references will be made.
c927aa0 @dhh Updated documentation
dhh authored
180 #
181 # * <tt>logger</tt> - the logger is used for generating information on the mailing run if available.
182 # Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers.
183 #
64092de @fxn Improve documentation coverage and markup
fxn authored
184 # * <tt>smtp_settings</tt> - Allows detailed configuration for <tt>:smtp</tt> delivery method:
dc4eec1 @lifo Merge docrails:
lifo authored
185 # * <tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting.
186 # * <tt>:port</tt> - On the off chance that your mail server doesn't run on port 25, you can change it.
187 # * <tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.
188 # * <tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.
189 # * <tt>:password</tt> - If your mail server requires authentication, set the password in this setting.
b2504f8 @josh Tidy up ActionMailer rendering logic to take advantage of view path cach...
josh authored
190 # * <tt>:authentication</tt> - If your mail server requires authentication, you need to specify the authentication type here.
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
191 # This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>.
c2e7851 @josevalim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
192 # * <tt>:enable_starttls_auto</tt> - When set to true, detects if STARTTLS is enabled in your SMTP server and starts to use it.
193 # It works only on Ruby >= 1.8.7 and Ruby >= 1.9. Default is true.
c927aa0 @dhh Updated documentation
dhh authored
194 #
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
195 # * <tt>sendmail_settings</tt> - Allows you to override options for the <tt>:sendmail</tt> delivery method.
196 # * <tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.
197 # * <tt>:arguments</tt> - The command line arguments. Defaults to <tt>-i -t</tt>.
dc4eec1 @lifo Merge docrails:
lifo authored
198 #
fbe6c3c @edavis10 Adds a :file delivery_method to save email to a file on disk
edavis10 authored
199 # * <tt>file_settings</tt> - Allows you to override options for the <tt>:file</tt> delivery method.
200 # * <tt>:location</tt> - The directory into which emails will be written. Defaults to the application <tt>tmp/mails</tt>.
201 #
dc4eec1 @lifo Merge docrails:
lifo authored
202 # * <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
203 #
fbe6c3c @edavis10 Adds a :file delivery_method to save email to a file on disk
edavis10 authored
204 # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, <tt>:test</tt>,
f4f7677 @matthewrudy abstract all of the ActionMailer delivery methods into their own classes...
matthewrudy authored
205 # and <tt>:file</tt>. Or you may provide a custom delivery method object eg. MyOwnDeliveryMethodClass.new
c927aa0 @dhh Updated documentation
dhh authored
206 #
dc4eec1 @lifo Merge docrails:
lifo authored
207 # * <tt>perform_deliveries</tt> - Determines whether <tt>deliver_*</tt> methods are actually carried out. By default they are,
c927aa0 @dhh Updated documentation
dhh authored
208 # but this can be turned off to help functional testing.
209 #
64092de @fxn Improve documentation coverage and markup
fxn authored
210 # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with <tt>delivery_method :test</tt>. Most useful
c927aa0 @dhh Updated documentation
dhh authored
211 # for unit and functional testing.
af56c80 @dhh Updated documentation
dhh authored
212 #
b2504f8 @josh Tidy up ActionMailer rendering logic to take advantage of view path cach...
josh authored
213 # * <tt>default_charset</tt> - The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
214 # pick a different charset from inside a method with +charset+.
c2e7851 @josevalim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
215 #
475bd74 @dhh Fix docs (closes #2598)
dhh authored
216 # * <tt>default_content_type</tt> - The default content type used for the main part of the message. Defaults to "text/plain". You
b2504f8 @josh Tidy up ActionMailer rendering logic to take advantage of view path cach...
josh authored
217 # can also pick a different content type from inside a method with +content_type+.
c2e7851 @josevalim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
218 #
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
219 # * <tt>default_mime_version</tt> - The default mime version used for the message. Defaults to <tt>1.0</tt>. You
220 # can also pick a different value from inside a method with +mime_version+.
c2e7851 @josevalim Add ActionMailer::Base#enable_starttls_auto option for enabling/disablin...
josevalim authored
221 #
475bd74 @dhh Fix docs (closes #2598)
dhh authored
222 # * <tt>default_implicit_parts_order</tt> - When a message is built implicitly (i.e. multiple parts are assembled from templates
5c98152 @jamis Better multipart support with implicit multipart/alternative and sorting...
jamis authored
223 # which specify the content type in their filenames) this variable controls how the parts are ordered. Defaults to
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
224 # <tt>["text/html", "text/enriched", "text/plain"]</tt>. Items that appear first in the array have higher priority in the mail client
5c98152 @jamis Better multipart support with implicit multipart/alternative and sorting...
jamis authored
225 # and appear last in the mime encoded message. You can also pick a different order from inside a method with
46f30f9 @lifo Merge documentation changes from docrails.
lifo authored
226 # +implicit_parts_order+.
4964d3b @josevalim Make ActionMailer::Base inherit from AbstractController::Base
josevalim authored
227 class Base < AbstractController::Base
0d931fe Finish cleaning up delivery methods implementation.
José Valim and Mikel Lindsaar authored
228 include DeliveryMethods, Quoting
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
229 abstract!
230
c03c40b @josevalim Expose a _render_partial hook as thhe _render_template one and make use ...
josevalim authored
231 include AbstractController::Logger
83f4d86 @dhh Rename the RenderingController module to just plain Rendering
dhh authored
232 include AbstractController::Rendering
976c264 @josevalim Extracted localized_cache.rb from ActionController, added it to Abstract...
josevalim authored
233 include AbstractController::LocalizedCache
a9751a7 @josevalim Refactor ActionMailer layout and remove legacy one.
josevalim authored
234 include AbstractController::Layouts
684c2dc @josevalim Remove ActionMailer helpers and rely on AbstractController one.
josevalim authored
235 include AbstractController::Helpers
f564f94 @josevalim Remove duplicated url_for code and move methods shared between ActionMai...
josevalim authored
236 include AbstractController::UrlFor
359caef @jamis A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
237
ee70d1b @josevalim adv_attr_accessors in ActionMailer are not sent to the views, use the ma...
josevalim authored
238 helper ActionMailer::MailHelper
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
239
5dead5b Maintain old_api and deprecated_api in different files.
José Valim and Mikel Lindsaar authored
240 include ActionMailer::OldApi
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
241 include ActionMailer::DeprecatedApi
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
242
c927aa0 @dhh Updated documentation
dhh authored
243 private_class_method :new #:nodoc:
db045db @dhh Initial
dhh authored
244
e1c1318 Added delivers_from.
José Valim and Mikel Lindsaar authored
245 extlib_inheritable_accessor :default_from
246 self.default_from = nil
247
b30eb39 Add more tests to new API.
José Valim and Mikel Lindsaar authored
248 extlib_inheritable_accessor :default_charset
249 self.default_charset = "utf-8"
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
250
b30eb39 Add more tests to new API.
José Valim and Mikel Lindsaar authored
251 extlib_inheritable_accessor :default_content_type
252 self.default_content_type = "text/plain"
3b0e1d9 @josh Prefer string core_ext inflector methods over directly accessing Inflect...
josh authored
253
b30eb39 Add more tests to new API.
José Valim and Mikel Lindsaar authored
254 extlib_inheritable_accessor :default_mime_version
255 self.default_mime_version = "1.0"
100fd72 @jamis Added a "content_type" accessor to allow messages to explicitly specify ...
jamis authored
256
c039bcd @mikel Moved sort_parts into Mail, updated mail requirement to 1.4.2
mikel authored
257 # This specifies the order that the parts of a multipart email will be. Usually you put
258 # text/plain at the top so someone without a MIME capable email reader can read the plain
259 # text of your email first.
260 #
261 # Any content type that is not listed here will be inserted in the order you add them to
262 # the email after the content types you list here.
b30eb39 Add more tests to new API.
José Valim and Mikel Lindsaar authored
263 extlib_inheritable_accessor :default_implicit_parts_order
264 self.default_implicit_parts_order = [ "text/plain", "text/enriched", "text/html" ]
5c98152 @jamis Better multipart support with implicit multipart/alternative and sorting...
jamis authored
265
eda1719 @jamis ActionMailer::Base.deliver(email) had been accidentally removed, but was...
jamis authored
266 class << self
bd5ed65 @technoweenie Update ActionMailer so it treats ActionView the same way that ActionCont...
technoweenie authored
267 def mailer_name
268 @mailer_name ||= name.underscore
269 end
0750304 @mikel Migrated over to Mail doing delivery.
mikel authored
270 attr_writer :mailer_name
271 alias :controller_path :mailer_name
81c416b @josevalim More refactoring on ActionMailer::Base.
josevalim authored
272
e1c1318 Added delivers_from.
José Valim and Mikel Lindsaar authored
273 # Sets who is the default sender for the e-mail
274 def delivers_from(value = nil)
275 self.default_from = value if value
276 self.default_from
277 end
278
59f1df1 @jamis Update/extend ActionMailer documentation (rdoc)
jamis authored
279 # Receives a raw email, parses it into an email object, decodes it,
280 # instantiates a new mailer, and passes the email object to the mailer
98dc582 @lifo Merge docrails.
lifo authored
281 # object's +receive+ method. If you want your mailer to be able to
282 # process incoming messages, you'll need to implement a +receive+
59f1df1 @jamis Update/extend ActionMailer documentation (rdoc)
jamis authored
283 # method that accepts the email object as a parameter:
284 #
285 # class MyMailer < ActionMailer::Base
286 # def receive(mail)
287 # ...
288 # end
289 # end
704daad @josevalim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
290 def receive(raw_mail)
291 ActiveSupport::Notifications.instrument("action_mailer.receive") do |payload|
292 mail = Mail.new(raw_mail)
293 set_payload_for_mail(payload, mail)
2a6bc12 @josevalim Add subscriber to ActionMailer.
josevalim authored
294 new.receive(mail)
295 end
eda1719 @jamis ActionMailer::Base.deliver(email) had been accidentally removed, but was...
jamis authored
296 end
297
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
298 # Delivers a mail object. This is actually called by the <tt>Mail::Message</tt> object
299 # itself through a call back when you call <tt>:deliver</tt> on the Mail::Message,
300 # calling +deliver_mail+ directly and passing an Mail::Message will do nothing.
e4a989e Added delivery_handler method to mail and implemented in ActionMailer to...
José Valim and Mikel Lindsaar authored
301 def deliver_mail(mail) #:nodoc:
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
302 ActiveSupport::Notifications.instrument("action_mailer.deliver") do |payload|
258ca14 Delegated ActionMailer::Base.deliveries to Mail.deliveries, added callba...
José Valim and Mikel Lindsaar authored
303 self.set_payload_for_mail(payload, mail)
e4a989e Added delivery_handler method to mail and implemented in ActionMailer to...
José Valim and Mikel Lindsaar authored
304
ace7497 Got AM working with Mail yield on delivery_handler and updated tests
José Valim and Mikel Lindsaar authored
305 yield # Let Mail do the delivery actions
e4a989e Added delivery_handler method to mail and implemented in ActionMailer to...
José Valim and Mikel Lindsaar authored
306
258ca14 Delegated ActionMailer::Base.deliveries to Mail.deliveries, added callba...
José Valim and Mikel Lindsaar authored
307 end
308 end
309
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
310 def respond_to?(method, *args) #:nodoc:
311 super || action_methods.include?(method.to_s)
312 end
313
314 protected
315
704daad @josevalim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
316 def set_payload_for_mail(payload, mail) #:nodoc:
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
317 payload[:mailer] = self.name
c905fce @josevalim Add message_id to AM payload and don't send bcc and cc if they were not ...
josevalim authored
318 payload[:message_id] = mail.message_id
319 payload[:subject] = mail.subject
320 payload[:to] = mail.to
321 payload[:from] = mail.from
322 payload[:bcc] = mail.bcc if mail.bcc.present?
323 payload[:cc] = mail.cc if mail.cc.present?
324 payload[:date] = mail.date
325 payload[:mail] = mail.encoded
704daad @josevalim Ensure we just send Ruby Stdlib objects in ActionMailer notifications.
josevalim authored
326 end
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
327
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
328 def method_missing(method, *args) #:nodoc:
f30d73b Add new class delivery method API.
José Valim and Mikel Lindsaar authored
329 if action_methods.include?(method.to_s)
330 new(method, *args).message
331 else
332 super
333 end
334 end
eda1719 @jamis ActionMailer::Base.deliver(email) had been accidentally removed, but was...
jamis authored
335 end
336
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
337 attr_internal :message
338
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
339 # Instantiate a new mailer object. If +method_name+ is not +nil+, the mailer
340 # will be initialized according to the named method. If not, the mailer will
341 # remain uninitialized (useful when you only need to invoke the "receive"
342 # method, for instance).
343 def initialize(method_name=nil, *args)
344 super()
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
345 @_message = Mail.new
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
346 process(method_name, *args) if method_name
347 end
348
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
349 # Allows you to pass random and unusual headers to the new +Mail::Message+ object
350 # which will add them to itself.
351 #
352 # headers['X-Special-Domain-Specific-Header'] = "SecretValue"
353 #
354 # The resulting Mail::Message will have the following in it's header:
355 #
356 # X-Special-Domain-Specific-Header: SecretValue
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
357 def headers(args=nil)
358 if args
359 ActiveSupport::Deprecation.warn "headers(Hash) is deprecated, please do headers[key] = value instead", caller[0,2]
360 @headers = args
361 else
362 @_message
363 end
364 end
c34cfcc @mikel Created mail method for new API
mikel authored
365
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
366 # Allows you to add attachments to an email, like so:
367 #
368 # mail.attachments['filename.jpg'] = File.read('/path/to/filename.jpg')
369 #
370 # If you do this, then Mail will take the file name and work out the mime type
371 # set the Content-Type, Content-Disposition, Content-Transfer-Encoding and
372 # base64 encode the contents of the attachment all for you.
373 #
374 # You can also specify overrides if you want by passing a hash instead of a string:
375 #
376 # mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
377 # :content => File.read('/path/to/filename.jpg')}
378 #
379 # If you want to use a different encoding than Base64, you can pass an encoding in,
380 # but then it is up to you to pass in the content pre-encoded, and don't expect
381 # Mail to know how to decode this data:
382 #
383 # file_content = SpecialEncode(File.read('/path/to/filename.jpg'))
384 # mail.attachments['filename.jpg'] = {:mime_type => 'application/x-gzip',
385 # :encoding => 'SpecialEncoding',
386 # :content => file_content }
387 #
388 # You can also search for specific attachments:
389 #
390 # # By Filename
391 # mail.attachments['filename.jpg'] #=> Mail::Part object or nil
392 #
393 # # or by index
394 # mail.attachments[0] #=> Mail::Part (first attachment)
395 #
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
396 def attachments
397 @_message.attachments
398 end
dcb9253 Add basic template rendering to new DSL.
José Valim and Mikel Lindsaar authored
399
4a6eba3 Added initial documentation for the new API
José Valim and Mikel Lindsaar authored
400 # The main method that creates the message and renders the email templates. There are
401 # two ways to call this method, with a block, or without a block.
402 #
403 # Both methods accept a headers hash. This hash allows you to specify the most used headers
404 # in an email message, these are:
405 #
406 # * <tt>:subject</tt> - The subject of the message, if this is omitted, ActionMailer will
407 # ask the Rails I18n class for a translated <tt>:subject</tt> in the scope of
408 # <tt>[:actionmailer, mailer_scope, action_name]</tt> or if this is missing, will translate the
409 # humanized version of the <tt>action_name</tt>
410 # * <tt>:to</tt> - Who the message is destined for, can be a string of addresses, or an array
411 # of addresses.
412 # * <tt>:from</tt> - Who the message is from, if missing, will use the <tt>:delivers_from</tt>
413 # value in the class (if it exists)
414 # * <tt>:cc</tt> - Who you would like to Carbon-Copy on this email, can be a string of addresses,
415 # or an array of addresses.
416 # * <tt>:bcc</tt> - Who you would like to Blind-Carbon-Copy on this email, can be a string of
417 # addresses, or an array of addresses.
418 # * <tt>:reply_to</tt> - Who to set the Reply-To header of the email to.
419 # * <tt>:date</tt> - The date to say the email was sent on.
420 #
421 # If you need other headers not listed above, use the <tt>headers['name'] = value</tt> method.
422 #
423 # When a <tt>:return_path</tt> is specified, that value will be used as the 'envelope from'
424 # address for the Mail message. Setting this is useful when you want delivery notifications
425 # sent to a different address than the one in <tt>:from</tt>. Mail will actually use the
426 # <tt>:return_path</tt> in preference to the <tt>:sender</tt> in preference to the <tt>:from</tt>
427 # field for the 'envelope from' value.
428 #
429 # If you do not pass a block to the +mail+ method, it will find all templates in the
430 # template path that match the method name that it is being called from, it will then
431 # create parts for each of these templates intelligently, making educated guesses
432 # on correct content type and sequence, and return a fully prepared Mail::Message
433 # ready to call <tt>:deliver</tt> on to send.
434 #
435 # If you do pass a block, you can render specific templates of your choice:
436 #
437 # mail(:to => 'mikel@test.lindsaar.net') do |format|
438 # format.text
439 # format.html
440 # end
441 #
442 # You can even render text directly without using a template:
443 #
444 # mail(:to => 'mikel@test.lindsaar.net') do |format|
445 # format.text { render :text => "Hello Mikel!" }
446 # format.html { render :text => "<h1>Hello Mikel!</h1>" }
447 # end
448 #
449 # Which will render a <tt>multipart/alternate</tt> email with <tt>text/plain</tt> and
450 # <tt>text/html</tt> parts.
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
451 def mail(headers={}, &block)
452 # Guard flag to prevent both the old and the new API from firing
453 # Should be removed when old API is removed
454 @mail_was_called = true
455 m = @_message
258ca14 Delegated ActionMailer::Base.deliveries to Mail.deliveries, added callba...
José Valim and Mikel Lindsaar authored
456
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
457 # Give preference to headers and fallback to the ones set in mail
1cd5592 First work on implicit multipart.
José Valim and Mikel Lindsaar authored
458 content_type = headers[:content_type] || m.content_type
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
459 charset = headers[:charset] || m.charset || self.class.default_charset.dup
460 mime_version = headers[:mime_version] || m.mime_version || self.class.default_mime_version.dup
1cd5592 First work on implicit multipart.
José Valim and Mikel Lindsaar authored
461
e1c1318 Added delivers_from.
José Valim and Mikel Lindsaar authored
462 # Set fields quotings
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
463 headers[:subject] ||= default_subject
e1c1318 Added delivers_from.
José Valim and Mikel Lindsaar authored
464 headers[:from] ||= self.class.default_from.dup
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
465 quote_fields!(headers, charset)
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
466
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
467 # Render the templates and blocks
468 responses, sort_order = collect_responses_and_sort_order(headers, &block)
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
469 content_type ||= create_parts_from_responses(m, responses, charset)
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
470
471 # Tidy up content type, charset, mime version and sort order
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
472 m.content_type = content_type
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
473 m.charset = charset
474 m.mime_version = mime_version
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
475 sort_order = headers[:parts_order] || sort_order || self.class.default_implicit_parts_order.dup
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
476
e7e4ed4 Set sort order for explicit parts from the collector's template sequence
José Valim and Mikel Lindsaar authored
477 if m.multipart?
478 m.body.set_sort_order(sort_order)
951397b Get implicit multipart and attachments working together.
José Valim and Mikel Lindsaar authored
479 m.body.sort_parts!
480 end
bb9d71f Move class methods to deprecated stuff.
José Valim and Mikel Lindsaar authored
481
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
482 # Finaly set delivery behavior configured in class
483 wrap_delivery_behavior!(headers[:delivery_method])
c34cfcc @mikel Created mail method for new API
mikel authored
484 m
485 end
486
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
487 protected
488
489 def default_subject #:nodoc:
5c3ef8c Refactor subject with i18n.
José Valim and Mikel Lindsaar authored
490 mailer_scope = self.class.mailer_name.gsub('/', '.')
491 I18n.t(:subject, :scope => [:actionmailer, mailer_scope, action_name], :default => action_name.humanize)
492 end
493
73a9000 Adding failing tests for calling just the action, instead of :create_act...
José Valim and Mikel Lindsaar authored
494 # TODO: Move this into Mail
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
495 def quote_fields!(headers, charset) #:nodoc:
496 m = @_message
497 m.subject ||= quote_if_necessary(headers[:subject], charset) if headers[:subject]
498 m.to ||= quote_address_if_necessary(headers[:to], charset) if headers[:to]
499 m.from ||= quote_address_if_necessary(headers[:from], charset) if headers[:from]
500 m.cc ||= quote_address_if_necessary(headers[:cc], charset) if headers[:cc]
501 m.bcc ||= quote_address_if_necessary(headers[:bcc], charset) if headers[:bcc]
502 m.reply_to ||= quote_address_if_necessary(headers[:reply_to], charset) if headers[:reply_to]
503 m.date ||= headers[:date] if headers[:date]
504 end
505
506 def collect_responses_and_sort_order(headers) #:nodoc:
507 responses, sort_order = [], nil
508
509 if block_given?
510 collector = ActionMailer::Collector.new(self) { render(action_name) }
511 yield(collector)
512 sort_order = collector.responses.map { |r| r[:content_type] }
513 responses = collector.responses
514 elsif headers[:body]
515 responses << {
516 :body => headers[:body],
517 :content_type => self.class.default_content_type.dup
518 }
519 else
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
520 each_template do |template|
7409b73 Some refactoring.
José Valim and Mikel Lindsaar authored
521 responses << {
522 :body => render_to_body(:_template => template),
523 :content_type => template.mime_type.to_s
524 }
525 end
526 end
527
528 [responses, sort_order]
529 end
530
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
531 def each_template(&block) #:nodoc:
532 self.class.view_paths.each do |load_paths|
533 templates = load_paths.find_all(action_name, {}, self.class.mailer_name)
0ece244 Ensure implicit multipart templates with locale works as expected.
José Valim and Mikel Lindsaar authored
534 templates = templates.uniq_by { |t| t.details[:formats] }
535
99f960a Handle some TODOs and deprecations.
José Valim and Mikel Lindsaar authored
536 unless templates.empty?
537 templates.each(&block)
538 return
539 end
540 end
541 end
542
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
543 def create_parts_from_responses(m, responses, charset) #:nodoc:
544 if responses.size == 1 && !m.has_attachments?
545 m.body = responses[0][:body]
546 return responses[0][:content_type]
547 elsif responses.size > 1 && m.has_attachments?
548 container = Mail::Part.new
549 container.content_type = "multipart/alternate"
550 responses.each { |r| insert_part(container, r, charset) }
551 m.add_part(container)
552 else
553 responses.each { |r| insert_part(m, r, charset) }
554 end
555
556 m.has_attachments? ? "multipart/mixed" : "multipart/alternate"
359caef @jamis A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
557 end
558
6ba9446 Make implicit and explicit templates pass through the same part creation...
José Valim and Mikel Lindsaar authored
559 def insert_part(container, response, charset) #:nodoc:
560 response[:charset] ||= charset
561 part = Mail::Part.new(response)
562 container.add_part(part)
359caef @jamis A very thorough refactoring, resulting in new mail property setters and ...
jamis authored
563 end
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
564
db045db @dhh Initial
dhh authored
565 end
566 end
Something went wrong with that request. Please try again.