Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 235 lines (200 sloc) 9.131 kb
db045db @dhh Initial
dhh authored
1 module ActionMailer #:nodoc:
2 # Usage:
3 #
4 # class ApplicationMailer < ActionMailer::Base
5 # def post_notification(recipients, post)
165097e @dhh Added access to custom headers, like cc, bcc, and reply-to #268 [Andreas...
dhh authored
6 # @recipients = recipients
7 # @from = post.author.email_address_with_name
8 # @headers["bcc"] = SYSTEM_ADMINISTRATOR_EMAIL
9 # @headers["reply-to"] = "notifications@example.com"
10 # @subject = "[#{post.account.name} #{post.title}]"
11 # @body["post"] = post
db045db @dhh Initial
dhh authored
12 # end
13 #
14 # def comment_notification(recipient, comment)
15 # @recipients = recipient.email_address_with_name
16 # @subject = "[#{comment.post.project.client.firm.account.name}]" +
17 # " Re: #{comment.post.title}"
18 # @body["comment"] = comment
19 # @from = comment.author.email_address_with_name
20 # @sent_on = comment.posted_on
21 # end
22 # end
23 #
24 # # After this post_notification will look for "templates/application_mailer/post_notification.rhtml"
25 # ApplicationMailer.template_root = "templates"
26 #
27 # ApplicationMailer.create_comment_notification(david, hello_world) # => a tmail object
28 # ApplicationMailer.deliver_comment_notification(david, hello_world) # sends the email
c927aa0 @dhh Updated documentation
dhh authored
29 #
30 # = Configuration options
31 #
32 # These options are specified on the class level, like <tt>ActionMailer::Base.template_root = "/my/templates"</tt>
33 #
34 # * <tt>template_root</tt> - template root determines the base from which template references will be made.
35 #
36 # * <tt>logger</tt> - the logger is used for generating information on the mailing run if available.
37 # Can be set to nil for no logging. Compatible with both Ruby's own Logger and Log4r loggers.
38 #
39 # * <tt>server_settings</tt> - Allows detailed configuration of the server:
40 # * <tt>:address</tt> Allows you to use a remote mail server. Just change it away from it's default "localhost" setting.
41 # * <tt>:port</tt> On the off change that your mail server doesn't run on port 25, you can change it.
42 # * <tt>:domain</tt> If you need to specify a HELO domain, you can do it here.
43 # * <tt>:user_name</tt> If your mail server requires authentication, set the username and password in these two settings.
44 # * <tt>:password</tt> If your mail server requires authentication, set the username and password in these two settings.
45 # * <tt>:authentication</tt> If your mail server requires authentication, you need to specify the authentication type here.
46 # This is a symbol and one of :plain, :login, :cram_md5
47 #
48 # * <tt>raise_delivery_errors</tt> - whether or not errors should be raised if the email fails to be delivered.
49 #
50 # * <tt>delivery_method</tt> - Defines a delivery method. Possible values are :smtp (default), :sendmail, and :test.
51 # Sendmail is assumed to be present at "/usr/sbin/sendmail".
52 #
53 # * <tt>perform_deliveries</tt> - Determines whether deliver_* methods are actually carried out. By default they are,
54 # but this can be turned off to help functional testing.
55 #
56 # * <tt>deliveries</tt> - Keeps an array of all the emails sent out through the Action Mailer with delivery_method :test. Most useful
57 # for unit and functional testing.
af56c80 @dhh Updated documentation
dhh authored
58 #
59 # * <tt>default_charset</tt> - The default charset used for the body and to encode the subject. Defaults to UTF-8. You can also
60 # pick a different charset from inside a method with <tt>@encoding</tt>.
db045db @dhh Initial
dhh authored
61 class Base
c927aa0 @dhh Updated documentation
dhh authored
62 private_class_method :new #:nodoc:
db045db @dhh Initial
dhh authored
63
64 cattr_accessor :template_root
65 cattr_accessor :logger
66
67 @@server_settings = {
68 :address => "localhost",
69 :port => 25,
70 :domain => 'localhost.localdomain',
71 :user_name => nil,
72 :password => nil,
73 :authentication => nil
74 }
75 cattr_accessor :server_settings
76
77 @@raise_delivery_errors = true
78 cattr_accessor :raise_delivery_errors
79
80 @@delivery_method = :smtp
81 cattr_accessor :delivery_method
82
83 @@perform_deliveries = true
84 cattr_accessor :perform_deliveries
85
86 @@deliveries = []
87 cattr_accessor :deliveries
88
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
89 @@default_charset = "utf-8"
90 cattr_accessor :default_charset
91
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] Add...
dhh authored
92 attr_accessor :recipients, :subject, :body, :from, :sent_on, :headers, :bcc, :cc, :charset
165097e @dhh Added access to custom headers, like cc, bcc, and reply-to #268 [Andreas...
dhh authored
93
94 def initialize
5f5b053 @dhh Fixed that bcc and cc should be settable through @bcc and @cc -- not jus...
dhh authored
95 @bcc = @cc = @from = @recipients = @sent_on = @subject = @body = nil
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
96 @charset = @@default_charset.dup
165097e @dhh Added access to custom headers, like cc, bcc, and reply-to #268 [Andreas...
dhh authored
97 @headers = {}
98 end
db045db @dhh Initial
dhh authored
99
100 class << self
101 def method_missing(method_symbol, *parameters)#:nodoc:
102 case method_symbol.id2name
103 when /^create_([_a-z]*)/
104 create_from_action($1, *parameters)
105 when /^deliver_([_a-z]*)/
106 begin
107 deliver(send("create_" + $1, *parameters))
108 rescue Object => e
109 raise e if raise_delivery_errors
110 end
425aa50 @dhh Added receiver method for incoming email
dhh authored
111 end
db045db @dhh Initial
dhh authored
112 end
113
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
114 def mail(to, subject, body, from, timestamp = nil, headers = {},
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] Add...
dhh authored
115 charset = @@default_charset
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
116 ) #:nodoc:
117 deliver(create(to, subject, body, from, timestamp, headers, charset))
db045db @dhh Initial
dhh authored
118 end
119
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
120 def create(to, subject, body, from, timestamp = nil, headers = {},
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] Add...
dhh authored
121 charset = @@default_charset
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
122 ) #:nodoc:
db045db @dhh Initial
dhh authored
123 m = TMail::Mail.new
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] Add...
dhh authored
124 m.subject, m.body = quote_any_if_necessary(charset, subject, body)
125 m.to, m.from = quote_any_address_if_necessary(charset, to, from)
126
db045db @dhh Initial
dhh authored
127 m.date = timestamp.respond_to?("to_time") ? timestamp.to_time : (timestamp || Time.now)
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
128
129 m.set_content_type "text", "plain", { "charset" => charset }
130
165097e @dhh Added access to custom headers, like cc, bcc, and reply-to #268 [Andreas...
dhh authored
131 headers.each do |k, v|
132 m[k] = v
133 end
134
db045db @dhh Initial
dhh authored
135 return m
136 end
137
138 def deliver(mail) #:nodoc:
139 logger.info "Sent mail:\n #{mail.encoded}" unless logger.nil?
140 send("perform_delivery_#{delivery_method}", mail) if perform_deliveries
141 end
142
af56c80 @dhh Updated documentation
dhh authored
143 def quoted_printable(text, charset)#:nodoc:
148f6d8 @dhh Made Action Mailer templates use UTF-8 as default
dhh authored
144 text = text.gsub( /[^a-z ]/i ) { "=%02x" % $&[0] }.gsub( / /, "_" )
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
145 "=?#{charset}?Q?#{text}?="
146 end
147
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] Add...
dhh authored
148 CHARS_NEEDING_QUOTING = /[\000-\011\013\014\016-\037\177-\377]/
149
150 # Quote the given text if it contains any "illegal" characters
151 def quote_if_necessary(text, charset)
152 (text =~ CHARS_NEEDING_QUOTING) ?
153 quoted_printable(text, charset) :
154 text
155 end
156
157 # Quote any of the given strings if they contain any "illegal" characters
158 def quote_any_if_necessary(charset, *args)
159 args.map { |v| quote_if_necessary(v, charset) }
160 end
161
162 # Quote the given address if it needs to be. The address may be a
163 # regular email address, or it can be a phrase followed by an address in
164 # brackets. The phrase is the only part that will be quoted, and only if
165 # it needs to be. This allows extended characters to be used in the
166 # "to", "from", "cc", and "bcc" headers.
167 def quote_address_if_necessary(address, charset)
168 if address =~ /^([^<>\s]+) (<.*>)$/
169 address = $2
170 phrase = quote_if_necessary($1, charset)
171 "#{phrase} #{address}"
172 else
173 address
174 end
175 end
176
177 # Quote any of the given addresses, if they need to be.
178 def quote_any_address_if_necessary(charset, *args)
179 args.map { |v| quote_address_if_necessary(v, charset) }
180 end
181
425aa50 @dhh Added receiver method for incoming email
dhh authored
182 def receive(raw_email)
183 logger.info "Received mail:\n #{raw_email}" unless logger.nil?
184 new.receive(TMail::Mail.parse(raw_email))
185 end
186
148f6d8 @dhh Made Action Mailer templates use UTF-8 as default
dhh authored
187 private
db045db @dhh Initial
dhh authored
188 def perform_delivery_smtp(mail)
189 Net::SMTP.start(server_settings[:address], server_settings[:port], server_settings[:domain],
190 server_settings[:user_name], server_settings[:password], server_settings[:authentication]) do |smtp|
baae5a1 @dhh Fixed sending of emails to use Tmail#from not the deprecated Tmail#from_...
dhh authored
191 smtp.sendmail(mail.encoded, mail.from, mail.destinations)
db045db @dhh Initial
dhh authored
192 end
193 end
194
195 def perform_delivery_sendmail(mail)
196 IO.popen("/usr/sbin/sendmail -i -t","w+") do |sm|
197 sm.print(mail.encoded)
198 sm.flush
199 end
200 end
201
202 def perform_delivery_test(mail)
203 deliveries << mail
204 end
205
206 def create_from_action(method_name, *parameters)
207 mailer = new
208 mailer.body = {}
209 mailer.send(method_name, *parameters)
210
5f5b053 @dhh Fixed that bcc and cc should be settable through @bcc and @cc -- not jus...
dhh authored
211 unless String === mailer.body then
212 mailer.body = render_body mailer, method_name
db045db @dhh Initial
dhh authored
213 end
214
5f5b053 @dhh Fixed that bcc and cc should be settable through @bcc and @cc -- not jus...
dhh authored
215 mail = create(mailer.recipients, mailer.subject, mailer.body,
3fad0cd @dhh Added support for charsets for both subject and body. The default charse...
dhh authored
216 mailer.from, mailer.sent_on, mailer.headers,
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] Add...
dhh authored
217 mailer.charset)
5f5b053 @dhh Fixed that bcc and cc should be settable through @bcc and @cc -- not jus...
dhh authored
218
256e800 @dhh Fixed quoting for all address headers, not just to #955 [Jamis Buck] Add...
dhh authored
219 mail.bcc = quote_address_if_necessary(mailer.bcc, mailer.charset) unless mailer.bcc.nil?
220 mail.cc = quote_address_if_necessary(mailer.cc, mailer.charset) unless mailer.cc.nil?
5f5b053 @dhh Fixed that bcc and cc should be settable through @bcc and @cc -- not jus...
dhh authored
221
db045db @dhh Initial
dhh authored
222 return mail
223 end
224
225 def render_body(mailer, method_name)
226 ActionView::Base.new(template_path, mailer.body).render_file(method_name)
227 end
228
229 def template_path
230 template_root + "/" + Inflector.underscore(self.to_s)
231 end
232 end
233 end
234 end
Something went wrong with that request. Please try again.