Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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