Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 358 lines (311 sloc) 14.037 kb
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
1 require 'action_mailer/adv_attr_accessor'
2 require 'action_mailer/part'
5ddffc8 @jamis Allow for nested parts in multipart mails #1570 [Flurin Egger]
jamis authored
3 require 'action_mailer/part_container'
bde3df2 @jamis Correctly normalize newlines in outgoing emails before encoding the b…
jamis authored
4 require 'action_mailer/utils'
508c26c @jamis BCC headers are removed when sending via SMTP
jamis authored
5 require 'tmail/net'
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
6
db045db @dhh Initial
dhh authored
7 module ActionMailer #:nodoc:
8 # Usage:
9 #
10 # class ApplicationMailer < ActionMailer::Base
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
11 # # Set up properties
12 # # (Properties can also be specified via accessor methods
13 # # i.e. self.subject = "foo") and instance variables (@subject = "foo").
14 # def signup_notification(recipient)
15 # recipients recipient.email_address_with_name
16 # subject "New account information"
2789b5d @dhh Tuned documentation for release (AM)
dhh authored
17 # body { "account" => recipient }
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
18 # from "system@example.com"
19 # end
20 #
21 # # explicitly specify multipart messages
22 # def signup_notification(recipient)
23 # recipients recipient.email_address_with_name
24 # subject "New account information"
25 # from "system@example.com"
26 #
27 # part :content_type => "text/html",
28 # :body => render_message("signup-as-html", :account => recipient)
29 #
30 # part "text/plain" do |p|
31 # p.body = render_message("signup-as-plain", :account => recipient)
32 # p.transfer_encoding = "base64"
33 # end
34 # end
35 #
36 # # attachments
37 # def signup_notification(recipient)
38 # recipients recipient.email_address_with_name
39 # subject "New account information"
40 # from "system@example.com"
41 #
42 # attachment :content_type => "image/jpeg",
43 # :body => File.read("an-image.jpg")
44 #
45 # attachment "application/pdf" do |a|
46 # a.body = generate_your_pdf_here()
47 # end
db045db @dhh Initial
dhh authored
48 # end
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
49 #
50 # # implicitly multipart messages
51 # def signup_notification(recipient)
52 # recipients recipient.email_address_with_name
53 # subject "New account information"
54 # from "system@example.com"
55 # body(:account => "recipient")
56 #
57 # # ActionMailer will automatically detect and use multipart templates,
58 # # where each template is named after the name of the action, followed
59 # # by the content type. Each such detected template will be added as
60 # # a separate part to the message.
61 # #
62 # # for example, if the following templates existed:
63 # # * signup_notification.text.plain.rhtml
64 # # * signup_notification.text.html.rhtml
65 # # * signup_notification.text.xml.rxml
66 # # * signup_notification.text.x-yaml.rhtml
67 # #
68 # # Each would be rendered and added as a separate part to the message,
69 # # with the corresponding content type. The same body hash is passed to
70 # # each template.
db045db @dhh Initial
dhh authored
71 # end
72 # end
73 #
74 # # After this post_notification will look for "templates/application_mailer/post_notification.rhtml"
75 # ApplicationMailer.template_root = "templates"
76 #
77 # ApplicationMailer.create_comment_notification(david, hello_world) # => a tmail object
78 # ApplicationMailer.deliver_comment_notification(david, hello_world) # sends the email
c927aa0 @dhh Updated documentation
dhh authored
79 #
80 # = Configuration options
81 #
82 # These options are specified on the class level, like <tt>ActionMailer::Base.template_root = "/my/templates"</tt>
83 #
84 # * <tt>template_root</tt> - template root determines the base from which template references will be made.
85 #
86 # * <tt>logger</tt> - the logger is used for generating information on the mailing run if available.
87 # Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers.
88 #
89 # * <tt>server_settings</tt> - Allows detailed configuration of the server:
90 # * <tt>:address</tt> Allows you to use a remote mail server. Just change it away from it's default "localhost" setting.
91 # * <tt>:port</tt> On the off change that your mail server doesn't run on port 25, you can change it.
92 # * <tt>:domain</tt> If you need to specify a HELO domain, you can do it here.
93 # * <tt>:user_name</tt> If your mail server requires authentication, set the username and password in these two settings.
94 # * <tt>:password</tt> If your mail server requires authentication, set the username and password in these two settings.
95 # * <tt>:authentication</tt> If your mail server requires authentication, you need to specify the authentication type here.
96 # This is a symbol and one of :plain, :login, :cram_md5
97 #
98 # * <tt>raise_delivery_errors</tt> - whether or not errors should be raised if the email fails to be delivered.
99 #
100 # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are :smtp (default), :sendmail, and :test.
101 # Sendmail is assumed to be present at "/usr/sbin/sendmail".
102 #
103 # * <tt>perform_deliveries</tt> - Determines whether deliver_* methods are actually carried out. By default they are,
104 # but this can be turned off to help functional testing.
105 #
106 # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful
107 # for unit and functional testing.
af56c80 @dhh Updated documentation
dhh authored
108 #
109 # * <tt>default_charset</tt> - The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also
5c98152 @jamis Better multipart support with implicit multipart/alternative and sort…
jamis authored
110 # pick a different charset from inside a method with <tt>@charset</tt>.
111 # * <tt>default_content_type</tt> - The default content type used for main part of the message. Defaults to "text/plain". You
112 # can also pick a different content type from inside a method with <tt>@content_type</tt>.
113 # * <tt>default_implicit_parts_order</tt> - When a message is built implicitly (i.e. multiple parts are assemble from templates
114 # which specify the content type in their filenames) this variable controls how the parts are ordered. Defaults to
115 # ["text/html", "text/enriched", "text/plain"]. Items that appear first in the array have higher priority in the mail client
116 # and appear last in the mime encoded message. You can also pick a different order from inside a method with
117 # <tt>@implicit_parts_order</tt>.
db045db @dhh Initial
dhh authored
118 class Base
0fe8e3d @dhh Added a config example in README #1626 [courtenay]
dhh authored
119 include AdvAttrAccessor, PartContainer
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
120
c927aa0 @dhh Updated documentation
dhh authored
121 private_class_method :new #:nodoc:
db045db @dhh Initial
dhh authored
122
123 cattr_accessor :template_root
124 cattr_accessor :logger
125
126 @@server_settings = {
127 :address => "localhost",
128 :port => 25,
129 :domain => 'localhost.localdomain',
130 :user_name => nil,
131 :password => nil,
132 :authentication => nil
133 }
134 cattr_accessor :server_settings
135
136 @@raise_delivery_errors = true
137 cattr_accessor :raise_delivery_errors
138
139 @@delivery_method = :smtp
140 cattr_accessor :delivery_method
141
142 @@perform_deliveries = true
143 cattr_accessor :perform_deliveries
144
145 @@deliveries = []
146 cattr_accessor :deliveries
147
3fad0cd @dhh Added support for charsets for both subject and body. The default cha…
dhh authored
148 @@default_charset = "utf-8"
149 cattr_accessor :default_charset
150
100fd72 @jamis Added a "content_type" accessor to allow messages to explicitly speci…
jamis authored
151 @@default_content_type = "text/plain"
152 cattr_accessor :default_content_type
153
5c98152 @jamis Better multipart support with implicit multipart/alternative and sort…
jamis authored
154 @@default_implicit_parts_order = [ "text/html", "text/enriched", "text/plain" ]
155 cattr_accessor :default_implicit_parts_order
156
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
157 adv_attr_accessor :recipients, :subject, :body, :from, :sent_on, :headers,
5c98152 @jamis Better multipart support with implicit multipart/alternative and sort…
jamis authored
158 :bcc, :cc, :charset, :content_type, :implicit_parts_order,
159 :template
165097e @dhh Added access to custom headers, like cc, bcc, and reply-to #268 [Andr…
dhh authored
160
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
161 attr_reader :mail
162
163 # Instantiate a new mailer object. If +method_name+ is not +nil+, the mailer
164 # will be initialized according to the named method. If not, the mailer will
165 # remain uninitialized (useful when you only need to invoke the "receive"
166 # method, for instance).
2789b5d @dhh Tuned documentation for release (AM)
dhh authored
167 def initialize(method_name=nil, *parameters) #:nodoc:
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
168 create!(method_name, *parameters) if method_name
169 end
170
171 # Initialize the mailer via the given +method_name+. The body will be
172 # rendered and a new TMail::Mail object created.
2789b5d @dhh Tuned documentation for release (AM)
dhh authored
173 def create!(method_name, *parameters) #:nodoc:
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
174 @bcc = @cc = @from = @recipients = @sent_on = @subject = nil
3fad0cd @dhh Added support for charsets for both subject and body. The default cha…
dhh authored
175 @charset = @@default_charset.dup
100fd72 @jamis Added a "content_type" accessor to allow messages to explicitly speci…
jamis authored
176 @content_type = @@default_content_type.dup
5c98152 @jamis Better multipart support with implicit multipart/alternative and sort…
jamis authored
177 @implicit_parts_order = @@default_implicit_parts_order.dup
813a8b9 @jamis Allow template to be explicitly specified #1448 [tuxie@dekadance.se]
jamis authored
178 @template = method_name
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
179 @parts = []
165097e @dhh Added access to custom headers, like cc, bcc, and reply-to #268 [Andr…
dhh authored
180 @headers = {}
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
181 @body = {}
182
183 send(method_name, *parameters)
184
185 # If an explicit, textual body has not been set, we check assumptions.
186 unless String === @body
187 # First, we look to see if there are any likely templates that match,
188 # which include the content-type in their file name (i.e.,
189 # "the_template_file.text.html.rhtml", etc.).
190 if @parts.empty?
813a8b9 @jamis Allow template to be explicitly specified #1448 [tuxie@dekadance.se]
jamis authored
191 templates = Dir.glob("#{template_path}/#{@template}.*")
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
192 templates.each do |path|
193 type = (File.basename(path).split(".")[1..-2] || []).join("/")
194 next if type.empty?
195 @parts << Part.new(:content_type => type,
053cb22 @jamis Use the real charset for parts generated by a template, instead of th…
jamis authored
196 :disposition => "inline", :charset => charset,
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
197 :body => render_message(File.basename(path).split(".")[0..-2].join('.'), @body))
198 end
5c98152 @jamis Better multipart support with implicit multipart/alternative and sort…
jamis authored
199 unless @parts.empty?
200 @content_type = "multipart/alternative"
201 @parts = sort_parts(@parts, @implicit_parts_order)
202 end
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
203 end
db045db @dhh Initial
dhh authored
204
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
205 # Then, if there were such templates, we check to see if we ought to
206 # also render a "normal" template (without the content type). If a
207 # normal template exists (or if there were no implicit parts) we render
208 # it.
209 template_exists = @parts.empty?
813a8b9 @jamis Allow template to be explicitly specified #1448 [tuxie@dekadance.se]
jamis authored
210 template_exists ||= Dir.glob("#{template_path}/#{@template}.*").any? { |i| i.split(".").length == 2 }
211 @body = render_message(@template, @body) if template_exists
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
212
213 # Finally, if there are other message parts and a textual body exists,
214 # we shift it onto the front of the parts and set the body to nil (so
215 # that create_mail doesn't try to render it in addition to the parts).
216 if !@parts.empty? && String === @body
217 @parts.unshift Part.new(:charset => charset, :body => @body)
218 @body = nil
425aa50 @dhh Added receiver method for incoming email
dhh authored
219 end
db045db @dhh Initial
dhh authored
220 end
221
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
222 # build the mail object itself
223 @mail = create_mail
224 end
db045db @dhh Initial
dhh authored
225
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
226 # Delivers the cached TMail::Mail object. If no TMail::Mail object has been
227 # created (via the #create! method, for instance) this will fail.
2789b5d @dhh Tuned documentation for release (AM)
dhh authored
228 def deliver! #:nodoc:
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
229 raise "no mail object available for delivery!" unless @mail
230 logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil?
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] …
dhh authored
231
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
232 begin
233 send("perform_delivery_#{delivery_method}", @mail) if perform_deliveries
234 rescue Object => e
235 raise e if raise_delivery_errors
236 end
3fad0cd @dhh Added support for charsets for both subject and body. The default cha…
dhh authored
237
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
238 return @mail
239 end
3fad0cd @dhh Added support for charsets for both subject and body. The default cha…
dhh authored
240
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
241 private
242 def render_message(method_name, body)
5ec990a @jamis Helper support for ActionMailer
jamis authored
243 initialize_template_class(body).render_file(method_name)
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
244 end
245
246 def template_path
247 template_root + "/" + Inflector.underscore(self.class.name)
db045db @dhh Initial
dhh authored
248 end
249
5ec990a @jamis Helper support for ActionMailer
jamis authored
250 def initialize_template_class(assigns)
251 ActionView::Base.new(template_path, assigns, self)
252 end
253
5c98152 @jamis Better multipart support with implicit multipart/alternative and sort…
jamis authored
254 def sort_parts(parts, order = [])
255 order = order.collect { |s| s.downcase }
256
257 parts = parts.sort do |a, b|
258 a_ct = a.content_type.downcase
259 b_ct = b.content_type.downcase
260
261 a_in = order.include? a_ct
262 b_in = order.include? b_ct
263
264 s = case
265 when a_in && b_in
266 order.index(a_ct) <=> order.index(b_ct)
267 when a_in
268 -1
269 when b_in
270 1
271 else
272 a_ct <=> b_ct
273 end
274
275 # reverse the ordering because parts that come last are displayed
276 # first in mail clients
277 (s * -1)
278 end
279
280 parts
281 end
282
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
283 def create_mail
284 m = TMail::Mail.new
74a612c @dhh Added that delivery errors are caught in a way so the mail is still r…
dhh authored
285
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
286 m.subject, = quote_any_if_necessary(charset, subject)
287 m.to, m.from = quote_any_address_if_necessary(charset, recipients, from)
288 m.bcc = quote_address_if_necessary(bcc, charset) unless bcc.nil?
289 m.cc = quote_address_if_necessary(cc, charset) unless cc.nil?
74a612c @dhh Added that delivery errors are caught in a way so the mail is still r…
dhh authored
290
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
291 m.date = sent_on.to_time rescue sent_on if sent_on
292 headers.each { |k, v| m[k] = v }
db045db @dhh Initial
dhh authored
293
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
294 if @parts.empty?
100fd72 @jamis Added a "content_type" accessor to allow messages to explicitly speci…
jamis authored
295 m.set_content_type content_type, nil, { "charset" => charset }
bde3df2 @jamis Correctly normalize newlines in outgoing emails before encoding the b…
jamis authored
296 m.body = Utils.normalize_new_lines(body)
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
297 else
298 if String === body
299 part = TMail::Mail.new
bde3df2 @jamis Correctly normalize newlines in outgoing emails before encoding the b…
jamis authored
300 part.body = Utils.normalize_new_lines(body)
100fd72 @jamis Added a "content_type" accessor to allow messages to explicitly speci…
jamis authored
301 part.set_content_type content_type, nil, { "charset" => charset }
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
302 part.set_content_disposition "inline"
303 m.parts << part
304 end
3fad0cd @dhh Added support for charsets for both subject and body. The default cha…
dhh authored
305
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
306 @parts.each do |p|
307 part = (TMail::Mail === p ? p : p.to_mail(self))
308 m.parts << part
309 end
3b4eb7a @jamis Allow specific "multipart/xxx" content-type to be set on multipart me…
jamis authored
310
311 m.set_content_type(content_type, nil, { "charset" => charset }) if content_type =~ /multipart/
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
312 end
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] …
dhh authored
313
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
314 @mail = m
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] …
dhh authored
315 end
316
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
317 def perform_delivery_smtp(mail)
508c26c @jamis BCC headers are removed when sending via SMTP
jamis authored
318 destinations = mail.destinations
319 mail.ready_to_send
320
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
321 Net::SMTP.start(server_settings[:address], server_settings[:port], server_settings[:domain],
322 server_settings[:user_name], server_settings[:password], server_settings[:authentication]) do |smtp|
508c26c @jamis BCC headers are removed when sending via SMTP
jamis authored
323 smtp.sendmail(mail.encoded, mail.from, destinations)
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
324 end
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] …
dhh authored
325 end
326
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
327 def perform_delivery_sendmail(mail)
328 IO.popen("/usr/sbin/sendmail -i -t","w+") do |sm|
bb62568 @dhh Fix problem with sendmail delivery where headers should be delimited …
dhh authored
329 sm.print(mail.encoded.gsub(/\r/, ''))
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
330 sm.flush
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] …
dhh authored
331 end
332 end
333
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
334 def perform_delivery_test(mail)
335 deliveries << mail
336 end
337
338 class << self
339 def method_missing(method_symbol, *parameters)#:nodoc:
340 case method_symbol.id2name
341 when /^create_([_a-z]\w*)/ then new($1, *parameters).mail
342 when /^deliver_([_a-z]\w*)/ then new($1, *parameters).deliver!
5ec990a @jamis Helper support for ActionMailer
jamis authored
343 when "new" then nil
344 else super
359caef @jamis A very thorough refactoring, resulting in new mail property setters a…
jamis authored
345 end
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] …
dhh authored
346 end
347
425aa50 @dhh Added receiver method for incoming email
dhh authored
348 def receive(raw_email)
349 logger.info "Received mail:\n #{raw_email}" unless logger.nil?
a2eb744 @dhh Added automatic decoding of base64 bodies #1214 [Jamis Buck]
dhh authored
350 mail = TMail::Mail.parse(raw_email)
351 mail.base64_decode
352 new.receive(mail)
425aa50 @dhh Added receiver method for incoming email
dhh authored
353 end
354
db045db @dhh Initial
dhh authored
355 end
356 end
357 end
Something went wrong with that request. Please try again.