3 = interface.rb Provides an interface to the TMail object
7 # Copyright (c) 1998-2003 Minero Aoki <aamine@loveruby.net>
9 # Permission is hereby granted, free of charge, to any person obtaining
10 # a copy of this software and associated documentation files (the
11 # "Software"), to deal in the Software without restriction, including
12 # without limitation the rights to use, copy, modify, merge, publish,
13 # distribute, sublicense, and/or sell copies of the Software, and to
14 # permit persons to whom the Software is furnished to do so, subject to
15 # the following conditions:
17 # The above copyright notice and this permission notice shall be
18 # included in all copies or substantial portions of the Software.
20 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
21 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
22 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
23 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
24 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
25 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
26 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28 # Note: Originally licensed under LGPL v2+. Using MIT license for Rails
29 # with permission of Minero Aoki.
32 # TMail::Mail objects get accessed primarily through the methods in this file.
42 # Allows you to query the mail object with a string to get the contents
43 # of the field you want.
45 # Returns a string of the exact contents of the field
47 # mail.from = "mikel <mikel@lindsaar.net>"
48 # mail.header_string("From") #=> "mikel <mikel@lindsaar.net>"
49 def header_string( name
, default
= nil )
50 h
= @header[name
.downcase
] or return default
60 def set_string_array_attr( key
, strs
)
63 @header.delete key
.downcase
65 store key
, strs
.join(', ')
69 private :set_string_array_attr
71 def set_string_attr( key
, str
)
75 @header.delete key
.downcase
79 private :set_string_attr
81 def set_addrfield( name
, arg
)
83 h
= HeaderField
.internal_new(name
, @config)
84 h
.addrs
.replace
[arg
].flatten
91 private :set_addrfield
93 def addrs2specs( addrs
)
94 return nil unless addrs
95 list
= addrs
.map
{|addr
|
96 if addr
.address_group
?
97 then addr
.map
{|a
| a
.spec
}
101 return nil if list
.empty
?
108 #== Date and Time methods
110 # Returns the date of the email message as per the "date" header value or returns
111 # nil by default (if no date field exists).
113 # You can also pass whatever default you want into this method and it will return
114 # that instead of nil if there is no date already set.
115 def date( default
= nil )
116 if h
= @header['date']
123 # Destructively sets the date of the mail object with the passed Time instance,
124 # returns a Time instance set to the date/time of the mail
130 # mail.date #=> Sat Nov 03 18:47:50 +1100 2007
131 # mail.date.class #=> Time
134 store
'Date', time2str(time
)
136 @header.delete
'date'
141 # Returns the time of the mail message formatted to your taste using a
142 # strftime format string. If no date set returns nil by default or whatever value
143 # you pass as the second optional parameter.
145 # time = Time.now # (on Nov 16 2007)
147 # mail.strftime("%D") #=> "11/16/07"
148 def strftime( fmt
, default
= nil )
156 #== Destination methods
158 # Return a TMail::Addresses instance for each entry in the "To:" field of the mail object header.
160 # If the "To:" field does not exist, will return nil by default or the value you
161 # pass as the optional parameter.
165 # mail = TMail::Mail.new
166 # mail.to_addrs #=> nil
167 # mail.to_addrs([]) #=> []
168 # mail.to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
169 # mail.to_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
170 def to_addrs( default
= nil )
178 # Return a TMail::Addresses instance for each entry in the "Cc:" field of the mail object header.
180 # If the "Cc:" field does not exist, will return nil by default or the value you
181 # pass as the optional parameter.
185 # mail = TMail::Mail.new
186 # mail.cc_addrs #=> nil
187 # mail.cc_addrs([]) #=> []
188 # mail.cc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
189 # mail.cc_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
190 def cc_addrs( default
= nil )
198 # Return a TMail::Addresses instance for each entry in the "Bcc:" field of the mail object header.
200 # If the "Bcc:" field does not exist, will return nil by default or the value you
201 # pass as the optional parameter.
205 # mail = TMail::Mail.new
206 # mail.bcc_addrs #=> nil
207 # mail.bcc_addrs([]) #=> []
208 # mail.bcc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
209 # mail.bcc_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
210 def bcc_addrs( default
= nil )
211 if h
= @header['bcc']
218 # Destructively set the to field of the "To:" header to equal the passed in string.
220 # TMail will parse your contents and turn each valid email address into a TMail::Address
221 # object before assigning it to the mail message.
225 # mail = TMail::Mail.new
226 # mail.to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
227 # mail.to_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
229 set_addrfield
'to', arg
232 # Destructively set the to field of the "Cc:" header to equal the passed in string.
234 # TMail will parse your contents and turn each valid email address into a TMail::Address
235 # object before assigning it to the mail message.
239 # mail = TMail::Mail.new
240 # mail.cc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
241 # mail.cc_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
243 set_addrfield
'cc', arg
246 # Destructively set the to field of the "Bcc:" header to equal the passed in string.
248 # TMail will parse your contents and turn each valid email address into a TMail::Address
249 # object before assigning it to the mail message.
253 # mail = TMail::Mail.new
254 # mail.bcc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
255 # mail.bcc_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
256 def bcc_addrs
=( arg
)
257 set_addrfield
'bcc', arg
260 # Returns who the email is to as an Array of email addresses as opposed to an Array of
261 # TMail::Address objects which is what Mail#to_addrs returns
265 # mail = TMail::Mail.new
266 # mail.to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
267 # mail.to #=> ["mikel@me.org", "mikel@you.org"]
268 def to( default
= nil )
269 addrs2specs(to_addrs(nil)) || default
272 # Returns who the email cc'd as an Array of email addresses as opposed to an Array of
273 # TMail::Address objects which is what Mail#to_addrs returns
277 # mail = TMail::Mail.new
278 # mail.cc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
279 # mail.cc #=> ["mikel@me.org", "mikel@you.org"]
280 def cc( default
= nil )
281 addrs2specs(cc_addrs(nil)) || default
284 # Returns who the email bcc'd as an Array of email addresses as opposed to an Array of
285 # TMail::Address objects which is what Mail#to_addrs returns
289 # mail = TMail::Mail.new
290 # mail.bcc = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
291 # mail.bcc #=> ["mikel@me.org", "mikel@you.org"]
292 def bcc( default
= nil )
293 addrs2specs(bcc_addrs(nil)) || default
296 # Destructively sets the "To:" field to the passed array of strings (which should be valid
301 # mail = TMail::Mail.new
302 # mail.to = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
303 # mail.to #=> ["mikel@abc.org", "mikel@xyz.org"]
304 # mail['to'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
306 set_string_array_attr
'To', strs
309 # Destructively sets the "Cc:" field to the passed array of strings (which should be valid
314 # mail = TMail::Mail.new
315 # mail.cc = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
316 # mail.cc #=> ["mikel@abc.org", "mikel@xyz.org"]
317 # mail['cc'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
319 set_string_array_attr
'Cc', strs
322 # Destructively sets the "Bcc:" field to the passed array of strings (which should be valid
327 # mail = TMail::Mail.new
328 # mail.bcc = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
329 # mail.bcc #=> ["mikel@abc.org", "mikel@xyz.org"]
330 # mail['bcc'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
332 set_string_array_attr
'Bcc', strs
335 #== Originator methods
337 # Return a TMail::Addresses instance for each entry in the "From:" field of the mail object header.
339 # If the "From:" field does not exist, will return nil by default or the value you
340 # pass as the optional parameter.
344 # mail = TMail::Mail.new
345 # mail.from_addrs #=> nil
346 # mail.from_addrs([]) #=> []
347 # mail.from = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
348 # mail.from_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
349 def from_addrs( default
= nil )
350 if h
= @header['from']
357 # Destructively set the to value of the "From:" header to equal the passed in string.
359 # TMail will parse your contents and turn each valid email address into a TMail::Address
360 # object before assigning it to the mail message.
364 # mail = TMail::Mail.new
365 # mail.from_addrs = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
366 # mail.from_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
367 def from_addrs
=( arg
)
368 set_addrfield
'from', arg
371 # Returns who the email is from as an Array of email address strings instead to an Array of
372 # TMail::Address objects which is what Mail#from_addrs returns
376 # mail = TMail::Mail.new
377 # mail.from = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
378 # mail.from #=> ["mikel@me.org", "mikel@you.org"]
379 def from( default
= nil )
380 addrs2specs(from_addrs(nil)) || default
383 # Destructively sets the "From:" field to the passed array of strings (which should be valid
388 # mail = TMail::Mail.new
389 # mail.from = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
390 # mail.from #=> ["mikel@abc.org", "mikel@xyz.org"]
391 # mail['from'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
393 set_string_array_attr
'From', strs
396 # Returns the "friendly" human readable part of the address
400 # mail = TMail::Mail.new
401 # mail.from = "Mikel Lindsaar <mikel@abc.com>"
402 # mail.friendly_from #=> "Mikel Lindsaar"
403 def friendly_from( default
= nil )
406 return default
unless a
407 return a
.phrase
if a
.phrase
408 return h
.comments
.join(' ') unless h
.comments
.empty
?
412 # Return a TMail::Addresses instance for each entry in the "Reply-To:" field of the mail object header.
414 # If the "Reply-To:" field does not exist, will return nil by default or the value you
415 # pass as the optional parameter.
419 # mail = TMail::Mail.new
420 # mail.reply_to_addrs #=> nil
421 # mail.reply_to_addrs([]) #=> []
422 # mail.reply_to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
423 # mail.reply_to_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
424 def reply_to_addrs( default
= nil )
425 if h
= @header['reply-to']
426 h
.addrs
.blank
? ? default
: h
.addrs
432 # Destructively set the to value of the "Reply-To:" header to equal the passed in argument.
434 # TMail will parse your contents and turn each valid email address into a TMail::Address
435 # object before assigning it to the mail message.
439 # mail = TMail::Mail.new
440 # mail.reply_to_addrs = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
441 # mail.reply_to_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
442 def reply_to_addrs
=( arg
)
443 set_addrfield
'reply-to', arg
446 # Returns who the email is from as an Array of email address strings instead to an Array of
447 # TMail::Address objects which is what Mail#reply_to_addrs returns
451 # mail = TMail::Mail.new
452 # mail.reply_to = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
453 # mail.reply_to #=> ["mikel@me.org", "mikel@you.org"]
454 def reply_to( default
= nil )
455 addrs2specs(reply_to_addrs(nil)) || default
458 # Destructively sets the "Reply-To:" field to the passed array of strings (which should be valid
463 # mail = TMail::Mail.new
464 # mail.reply_to = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
465 # mail.reply_to #=> ["mikel@abc.org", "mikel@xyz.org"]
466 # mail['reply_to'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"
467 def reply_to
=( *strs
)
468 set_string_array_attr
'Reply-To', strs
471 # Return a TMail::Addresses instance of the "Sender:" field of the mail object header.
473 # If the "Sender:" field does not exist, will return nil by default or the value you
474 # pass as the optional parameter.
478 # mail = TMail::Mail.new
479 # mail.sender #=> nil
480 # mail.sender([]) #=> []
481 # mail.sender = "Mikel <mikel@me.org>"
482 # mail.reply_to_addrs #=> [#<TMail::Address mikel@me.org>]
483 def sender_addr( default
= nil )
484 f
= @header['sender'] or return default
485 f
.addr
or return default
488 # Destructively set the to value of the "Sender:" header to equal the passed in argument.
490 # TMail will parse your contents and turn each valid email address into a TMail::Address
491 # object before assigning it to the mail message.
495 # mail = TMail::Mail.new
496 # mail.sender_addrs = "Mikel <mikel@me.org>, another Mikel <mikel@you.org>"
497 # mail.sender_addrs #=> [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]
498 def sender_addr
=( addr
)
500 h
= HeaderField
.internal_new('sender', @config)
502 @header['sender'] = h
504 @header.delete
'sender'
509 # Returns who the sender of this mail is as string instead to an Array of
510 # TMail::Address objects which is what Mail#sender_addr returns
514 # mail = TMail::Mail.new
515 # mail.sender = "Mikel <mikel@me.org>"
516 # mail.sender #=> "mikel@me.org"
517 def sender( default
= nil )
518 f
= @header['sender'] or return default
519 a
= f
.addr
or return default
523 # Destructively sets the "Sender:" field to the passed string (which should be a valid
528 # mail = TMail::Mail.new
529 # mail.sender = "mikel@abc.com"
530 # mail.sender #=> "mikel@abc.org"
531 # mail['sender'].to_s #=> "mikel@abc.com"
533 set_string_attr
'Sender', str
538 # Returns the subject of the mail instance.
540 # If the subject field does not exist, returns nil by default or you can pass in as
541 # the parameter for what you want the default value to be.
545 # mail = TMail::Mail.new
546 # mail.subject #=> nil
547 # mail.subject("") #=> ""
548 # mail.subject = "Hello"
549 # mail.subject #=> "Hello"
550 def subject( default
= nil )
551 if h
= @header['subject']
557 alias quoted_subject subject
559 # Destructively sets the passed string as the subject of the mail message.
563 # mail = TMail::Mail.new
564 # mail.subject #=> "This subject"
565 # mail.subject = "Another subject"
566 # mail.subject #=> "Another subject"
568 set_string_attr
'Subject', str
571 #== Message Identity & Threading Methods
573 # Returns the message ID for this mail object instance.
575 # If the message_id field does not exist, returns nil by default or you can pass in as
576 # the parameter for what you want the default value to be.
580 # mail = TMail::Mail.new
581 # mail.message_id #=> nil
582 # mail.message_id(TMail.new_message_id) #=> "<47404c5326d9c_2ad4fbb80161@baci.local.tmail>"
583 # mail.message_id = TMail.new_message_id
584 # mail.message_id #=> "<47404c5326d9c_2ad4fbb80161@baci.local.tmail>"
585 def message_id( default
= nil )
586 if h
= @header['message-id']
593 # Destructively sets the message ID of the mail object instance to the passed in string
595 # Invalid message IDs are ignored (silently, unless configured otherwise) and result in
596 # a nil message ID. Left and right angle brackets are required.
600 # mail = TMail::Mail.new
601 # mail.message_id = "<348F04F142D69C21-291E56D292BC@xxxx.net>"
602 # mail.message_id #=> "<348F04F142D69C21-291E56D292BC@xxxx.net>"
603 # mail.message_id = "this_is_my_badly_formatted_message_id"
604 # mail.message_id #=> nil
605 def message_id
=( str
)
606 set_string_attr
'Message-Id', str
609 # Returns the "In-Reply-To:" field contents as an array of this mail instance if it exists\10
611 # If the in_reply_to field does not exist, returns nil by default or you can pass in as
612 # the parameter for what you want the default value to be.
616 # mail = TMail::Mail.new
617 # mail.in_reply_to #=> nil
618 # mail.in_reply_to([]) #=> []
619 # TMail::Mail.load("../test/fixtures/raw_email_reply")
620 # mail.in_reply_to #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
621 def in_reply_to( default
= nil )
622 if h
= @header['in-reply-to']
629 # Destructively sets the value of the "In-Reply-To:" field of an email.
631 # Accepts an array of a single string of a message id
635 # mail = TMail::Mail.new
636 # mail.in_reply_to = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
637 # mail.in_reply_to #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
638 def in_reply_to
=( *idstrs
)
639 set_string_array_attr
'In-Reply-To', idstrs
642 # Returns the references of this email (prior messages relating to this message)
643 # as an array of message ID strings. Useful when you are trying to thread an
646 # If the references field does not exist, returns nil by default or you can pass in as
647 # the parameter for what you want the default value to be.
651 # mail = TMail::Mail.new
652 # mail.references #=> nil
653 # mail.references([]) #=> []
654 # mail = TMail::Mail.load("../test/fixtures/raw_email_reply")
655 # mail.references #=> ["<473FF3B8.9020707@xxx.org>", "<348F04F142D69C21-291E56D292BC@xxxx.net>"]
656 def references( default
= nil )
657 if h
= @header['references']
664 # Destructively sets the value of the "References:" field of an email.
666 # Accepts an array of strings of message IDs
670 # mail = TMail::Mail.new
671 # mail.references = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
672 # mail.references #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
673 def references
=( *strs
)
674 set_string_array_attr
'References', strs
677 #== MIME header methods
679 # Returns the listed MIME version of this email from the "Mime-Version:" header field
681 # If the mime_version field does not exist, returns nil by default or you can pass in as
682 # the parameter for what you want the default value to be.
686 # mail = TMail::Mail.new
687 # mail.mime_version #=> nil
688 # mail.mime_version([]) #=> []
689 # mail = TMail::Mail.load("../test/fixtures/raw_email")
690 # mail.mime_version #=> "1.0"
691 def mime_version( default
= nil )
692 if h
= @header['mime-version']
699 def mime_version
=( m
, opt
= nil )
701 if h
= @header['mime-version']
705 store
'Mime-Version', "#{m}.#{opt}"
708 store
'Mime-Version', m
713 # Returns the current "Content-Type" of the mail instance.
715 # If the content_type field does not exist, returns nil by default or you can pass in as
716 # the parameter for what you want the default value to be.
720 # mail = TMail::Mail.new
721 # mail.content_type #=> nil
722 # mail.content_type([]) #=> []
723 # mail = TMail::Mail.load("../test/fixtures/raw_email")
724 # mail.content_type #=> "text/plain"
725 def content_type( default
= nil )
726 if h
= @header['content-type']
727 h
.content_type
|| default
733 # Returns the current main type of the "Content-Type" of the mail instance.
735 # If the content_type field does not exist, returns nil by default or you can pass in as
736 # the parameter for what you want the default value to be.
740 # mail = TMail::Mail.new
741 # mail.main_type #=> nil
742 # mail.main_type([]) #=> []
743 # mail = TMail::Mail.load("../test/fixtures/raw_email")
744 # mail.main_type #=> "text"
745 def main_type( default
= nil )
746 if h
= @header['content-type']
747 h
.main_type
|| default
753 # Returns the current sub type of the "Content-Type" of the mail instance.
755 # If the content_type field does not exist, returns nil by default or you can pass in as
756 # the parameter for what you want the default value to be.
760 # mail = TMail::Mail.new
761 # mail.sub_type #=> nil
762 # mail.sub_type([]) #=> []
763 # mail = TMail::Mail.load("../test/fixtures/raw_email")
764 # mail.sub_type #=> "plain"
765 def sub_type( default
= nil )
766 if h
= @header['content-type']
767 h
.sub_type
|| default
773 # Destructively sets the "Content-Type:" header field of this mail object
775 # Allows you to set the main type, sub type as well as parameters to the field.
776 # The main type and sub type need to be a string.
778 # The optional params hash can be passed with keys as symbols and values as a string,
779 # or strings as keys and values.
783 # mail = TMail::Mail.new
784 # mail.set_content_type("text", "plain")
785 # mail.to_s #=> "Content-Type: text/plain\n\n"
787 # mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"})
788 # mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n"
790 # mail.set_content_type("text", "plain", {"charset" => "EUC-KR", "format" => "flowed"})
791 # mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n"
792 def set_content_type( str
, sub
= nil, param
= nil )
796 main
, sub
= str
.split(%r
</>, 2)
797 raise ArgumentError
, "sub type missing: #{str.inspect}" unless sub
799 if h
= @header['content-type']
804 store
'Content-Type', "#{main}/#{sub}"
806 @header['content-type'].params
.replace param
if param
810 alias content_type
= set_content_type
812 # Returns the named type parameter as a string, from the "Content-Type:" header.
816 # mail = TMail::Mail.new
817 # mail.type_param("charset") #=> nil
818 # mail.type_param("charset", []) #=> []
819 # mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"})
820 # mail.type_param("charset") #=> "EUC-KR"
821 # mail.type_param("format") #=> "flowed"
822 def type_param( name
, default
= nil )
823 if h
= @header['content-type']
830 # Returns the character set of the email. Returns nil if no encoding set or returns
831 # whatever default you pass as a parameter - note passing the parameter does NOT change
832 # the mail object in any way.
836 # mail = TMail::Mail.load("path_to/utf8_email")
837 # mail.charset #=> "UTF-8"
839 # mail = TMail::Mail.new
840 # mail.charset #=> nil
841 # mail.charset("US-ASCII") #=> "US-ASCII"
842 def charset( default
= nil )
843 if h
= @header['content-type']
844 h
['charset'] or default
850 # Destructively sets the character set used by this mail object to the passed string, you
851 # should note though that this does nothing to the mail body, just changes the header
852 # value, you will need to transliterate the body as well to match whatever you put
853 # in this header value if you are changing character sets.
857 # mail = TMail::Mail.new
858 # mail.charset #=> nil
859 # mail.charset = "UTF-8"
860 # mail.charset #=> "UTF-8"
863 if h
= @header[ 'content-type' ]
866 store
'Content-Type', "text/plain; charset=#{str}"
872 # Returns the transfer encoding of the email. Returns nil if no encoding set or returns
873 # whatever default you pass as a parameter - note passing the parameter does NOT change
874 # the mail object in any way.
878 # mail = TMail::Mail.load("path_to/base64_encoded_email")
879 # mail.transfer_encoding #=> "base64"
881 # mail = TMail::Mail.new
882 # mail.transfer_encoding #=> nil
883 # mail.transfer_encoding("base64") #=> "base64"
884 def transfer_encoding( default
= nil )
885 if h
= @header['content-transfer-encoding']
886 h
.encoding
|| default
892 # Destructively sets the transfer encoding of the mail object to the passed string, you
893 # should note though that this does nothing to the mail body, just changes the header
894 # value, you will need to encode or decode the body as well to match whatever you put
895 # in this header value.
899 # mail = TMail::Mail.new
900 # mail.transfer_encoding #=> nil
901 # mail.transfer_encoding = "base64"
902 # mail.transfer_encoding #=> "base64"
903 def transfer_encoding
=( str
)
904 set_string_attr
'Content-Transfer-Encoding', str
907 alias encoding transfer_encoding
908 alias encoding
= transfer_encoding
=
909 alias content_transfer_encoding transfer_encoding
910 alias content_transfer_encoding
= transfer_encoding
=
912 # Returns the content-disposition of the mail object, returns nil or the passed
913 # default value if given
917 # mail = TMail::Mail.load("path_to/raw_mail_with_attachment")
918 # mail.disposition #=> "attachment"
920 # mail = TMail::Mail.load("path_to/plain_simple_email")
921 # mail.disposition #=> nil
922 # mail.disposition(false) #=> false
923 def disposition( default
= nil )
924 if h
= @header['content-disposition']
925 h
.disposition
|| default
931 alias content_disposition disposition
933 # Allows you to set the content-disposition of the mail object. Accepts a type
934 # and a hash of parameters.
938 # mail.set_disposition("attachment", {:filename => "test.rb"})
939 # mail.disposition #=> "attachment"
940 # mail['content-disposition'].to_s #=> "attachment; filename=test.rb"
941 def set_disposition( str
, params
= nil )
942 if h
= @header['content-disposition']
946 store('Content-Disposition', str
)
947 h
= @header['content-disposition']
949 h
.params
.replace params
if params
952 alias disposition
= set_disposition
953 alias set_content_disposition set_disposition
954 alias content_disposition
= set_disposition
956 # Returns the value of a parameter in an existing content-disposition header
960 # mail.set_disposition("attachment", {:filename => "test.rb"})
961 # mail['content-disposition'].to_s #=> "attachment; filename=test.rb"
962 # mail.disposition_param("filename") #=> "test.rb"
963 # mail.disposition_param("missing_param_key") #=> nil
964 # mail.disposition_param("missing_param_key", false) #=> false
965 # mail.disposition_param("missing_param_key", "Nothing to see here") #=> "Nothing to see here"
966 def disposition_param( name
, default
= nil )
967 if h
= @header['content-disposition']
974 # Convert the Mail object's body into a Base64 encoded email
975 # returning the modified Mail object
977 store
'Content-Transfer-Encoding', 'Base64'
978 self.body
= base64_encode
981 # Return the result of encoding the TMail::Mail object body
982 # without altering the current body
984 Base64
.folding_encode(self.body
)
987 # Convert the Mail object's body into a Base64 decoded email
988 # returning the modified Mail object
990 if /base64/i
=== self.transfer_encoding('')
991 store
'Content-Transfer-Encoding', '8bit'
992 self.body
= base64_decode
996 # Returns the result of decoding the TMail::Mail object body
997 # without altering the current body
999 Base64
.decode(self.body
, @config.strict_base64decode
?)
1002 # Returns an array of each destination in the email message including to: cc: or bcc:
1006 # mail.to = "Mikel <mikel@lindsaar.net>"
1007 # mail.cc = "Trans <t@t.com>"
1008 # mail.bcc = "bob <bob@me.com>"
1009 # mail.destinations #=> ["mikel@lindsaar.net", "t@t.com", "bob@me.com"]
1010 def destinations( default
= nil )
1012 %w( to cc bcc
).each
do |nm
|
1014 h
.addrs
.each
{|i
| ret
.push i
.address
}
1017 ret
.empty
? ? default
: ret
1020 # Yields a block of destination, yielding each as a string.
1021 # (from the destinations example)
1022 # mail.each_destination { |d| puts "#{d.class}: #{d}" }
1023 # String: mikel@lindsaar.net
1025 # String: bob@me.com
1026 def each_destination( &block
)
1027 destinations([]).each
do |i
|
1036 alias each_dest each_destination
1038 # Returns an array of reply to addresses that the Mail object has,
1039 # or if the Mail message has no reply-to, returns an array of the
1040 # Mail objects from addresses. Else returns the default which can
1041 # either be passed as a parameter or defaults to nil
1044 # mail.from = "Mikel <mikel@lindsaar.net>"
1045 # mail.reply_to = nil
1046 # mail.reply_addresses #=> [""]
1048 def reply_addresses( default
= nil )
1049 reply_to_addrs(nil) or from_addrs(nil) or default
1052 # Returns the "sender" field as an array -> useful to find out who to
1053 # send an error email to.
1054 def error_reply_addresses( default
= nil )
1062 # Returns true if the Mail object is a multipart message
1064 main_type('').downcase
== 'multipart'
1067 # Creates a new email in reply to self. Sets the In-Reply-To and
1068 # References headers for you automagically.
1071 # mail = TMail::Mail.load("my_email")
1072 # reply_email = mail.create_reply
1073 # reply_email.class #=> TMail::Mail
1074 # reply_email.references #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"]
1075 # reply_email.in_reply_to #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"]
1077 setup_reply
create_empty_mail()
1080 # Creates a new email in reply to self. Sets the In-Reply-To and
1081 # References headers for you automagically.
1084 # mail = TMail::Mail.load("my_email")
1085 # forward_email = mail.create_forward
1086 # forward_email.class #=> TMail::Mail
1087 # forward_email.content_type #=> "multipart/mixed"
1088 # forward_email.body #=> "Attachment: (unnamed)"
1089 # forward_email.encoded #=> Returns the original email as a MIME attachment
1091 setup_forward
create_empty_mail()
1097 def create_empty_mail
1098 self.class.new(StringPort
.new(''), @config)
1101 def setup_reply( mail
)
1102 if tmp
= reply_addresses(nil)
1106 mid
= message_id(nil)
1107 tmp
= references(nil) || []
1109 mail
.in_reply_to
= [mid
] if mid
1110 mail
.references
= tmp
unless tmp
.empty
?
1111 mail
.subject
= 'Re: ' + subject('').sub(/\A(?:\[[^\]]+\])?(?:\s*Re:)*\s*/i
, '')
1112 mail
.mime_version
= '1.0'
1116 def setup_forward( mail
)
1117 m
= Mail
.new(StringPort
.new(''))
1119 m
.set_content_type
'message', 'rfc822'
1120 m
.encoding
= encoding('7bit')
1122 # call encoded to reparse the message