Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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