Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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