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.
598
# Be warned however, that calling mail.ready_to_send will overwrite whatever value you
599
# have in this field with an automatically generated unique value.
601
# If you really want to set your own message ID and know what you are doing per the
602
# various RFCs, you can do so with the enforced_message_id= command
606
# mail = TMail::Mail.new
607
# mail.message_id = "<348F04F142D69C21-291E56D292BC@xxxx.net>"
608
# mail.message_id #=> "<348F04F142D69C21-291E56D292BC@xxxx.net>"
609
# mail.message_id = "this_is_my_badly_formatted_message_id"
610
# mail.message_id #=> nil
611
def message_id=( str )
612
set_string_attr 'Message-Id', str
615
# Destructively sets the message ID of the mail object instance to the passed in string
616
# and also guarantees that calling #ready_to_send will not destroy what you set as the
621
# mail = TMail::Mail.new
622
# mail.message_id = "<348F04F142D69C21-291E56D292BC@xxxx.net>"
623
# mail.message_id #=> "<348F04F142D69C21-291E56D292BC@xxxx.net>"
625
# mail.message_id #=> "<348F04F142D69C21-291E56D292BC@xxxx.net>"
626
def enforced_message_id=( str )
627
@message_id_enforced = true
628
self.message_id = ( str )
631
# Returns the "In-Reply-To:" field contents as an array of this mail instance if it exists
633
# If the in_reply_to field does not exist, returns nil by default or you can pass in as
634
# the parameter for what you want the default value to be.
638
# mail = TMail::Mail.new
639
# mail.in_reply_to #=> nil
640
# mail.in_reply_to([]) #=> []
641
# TMail::Mail.load("../test/fixtures/raw_email_reply")
642
# mail.in_reply_to #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
643
def in_reply_to( default = nil )
644
if h = @header['in-reply-to']
651
# Destructively sets the value of the "In-Reply-To:" field of an email.
653
# Accepts an array of a single string of a message id
657
# mail = TMail::Mail.new
658
# mail.in_reply_to = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
659
# mail.in_reply_to #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
660
def in_reply_to=( *idstrs )
661
set_string_array_attr 'In-Reply-To', idstrs
664
# Returns the references of this email (prior messages relating to this message)
665
# as an array of message ID strings. Useful when you are trying to thread an
668
# If the references field does not exist, returns nil by default or you can pass in as
669
# the parameter for what you want the default value to be.
673
# mail = TMail::Mail.new
674
# mail.references #=> nil
675
# mail.references([]) #=> []
676
# mail = TMail::Mail.load("../test/fixtures/raw_email_reply")
677
# mail.references #=> ["<473FF3B8.9020707@xxx.org>", "<348F04F142D69C21-291E56D292BC@xxxx.net>"]
678
def references( default = nil )
679
if h = @header['references']
686
# Destructively sets the value of the "References:" field of an email.
688
# Accepts an array of strings of message IDs
692
# mail = TMail::Mail.new
693
# mail.references = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
694
# mail.references #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
695
def references=( *strs )
696
set_string_array_attr 'References', strs
699
#== MIME header methods
701
# Returns the listed MIME version of this email from the "Mime-Version:" header field
703
# If the mime_version field does not exist, returns nil by default or you can pass in as
704
# the parameter for what you want the default value to be.
708
# mail = TMail::Mail.new
709
# mail.mime_version #=> nil
710
# mail.mime_version([]) #=> []
711
# mail = TMail::Mail.load("../test/fixtures/raw_email")
712
# mail.mime_version #=> "1.0"
713
def mime_version( default = nil )
714
if h = @header['mime-version']
721
def mime_version=( m, opt = nil )
723
if h = @header['mime-version']
727
store 'Mime-Version', "#{m}.#{opt}"
730
store 'Mime-Version', m
735
# Returns the current "Content-Type" of the mail instance.
737
# If the content_type field does not exist, returns nil by default or you can pass in as
738
# the parameter for what you want the default value to be.
742
# mail = TMail::Mail.new
743
# mail.content_type #=> nil
744
# mail.content_type([]) #=> []
745
# mail = TMail::Mail.load("../test/fixtures/raw_email")
746
# mail.content_type #=> "text/plain"
747
def content_type( default = nil )
748
if h = @header['content-type']
749
h.content_type || default
755
# Returns the current main type of the "Content-Type" of the mail instance.
757
# If the content_type field does not exist, returns nil by default or you can pass in as
758
# the parameter for what you want the default value to be.
762
# mail = TMail::Mail.new
763
# mail.main_type #=> nil
764
# mail.main_type([]) #=> []
765
# mail = TMail::Mail.load("../test/fixtures/raw_email")
766
# mail.main_type #=> "text"
767
def main_type( default = nil )
768
if h = @header['content-type']
769
h.main_type || default
775
# Returns the current sub type of the "Content-Type" of the mail instance.
777
# If the content_type field does not exist, returns nil by default or you can pass in as
778
# the parameter for what you want the default value to be.
782
# mail = TMail::Mail.new
783
# mail.sub_type #=> nil
784
# mail.sub_type([]) #=> []
785
# mail = TMail::Mail.load("../test/fixtures/raw_email")
786
# mail.sub_type #=> "plain"
787
def sub_type( default = nil )
788
if h = @header['content-type']
789
h.sub_type || default
795
# Destructively sets the "Content-Type:" header field of this mail object
797
# Allows you to set the main type, sub type as well as parameters to the field.
798
# The main type and sub type need to be a string.
800
# The optional params hash can be passed with keys as symbols and values as a string,
801
# or strings as keys and values.
805
# mail = TMail::Mail.new
806
# mail.set_content_type("text", "plain")
807
# mail.to_s #=> "Content-Type: text/plain\n\n"
809
# mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"})
810
# mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n"
812
# mail.set_content_type("text", "plain", {"charset" => "EUC-KR", "format" => "flowed"})
813
# mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n"
814
def set_content_type( str, sub = nil, param = nil )
818
main, sub = str.split(%r</>, 2)
819
raise ArgumentError, "sub type missing: #{str.inspect}" unless sub
821
if h = @header['content-type']
826
store 'Content-Type', "#{main}/#{sub}"
828
@header['content-type'].params.replace param if param
832
alias content_type= set_content_type
834
# Returns the named type parameter as a string, from the "Content-Type:" header.
838
# mail = TMail::Mail.new
839
# mail.type_param("charset") #=> nil
840
# mail.type_param("charset", []) #=> []
841
# mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"})
842
# mail.type_param("charset") #=> "EUC-KR"
843
# mail.type_param("format") #=> "flowed"
844
def type_param( name, default = nil )
845
if h = @header['content-type']
852
# Returns the character set of the email. Returns nil if no encoding set or returns
853
# whatever default you pass as a parameter - note passing the parameter does NOT change
854
# the mail object in any way.
858
# mail = TMail::Mail.load("path_to/utf8_email")
859
# mail.charset #=> "UTF-8"
861
# mail = TMail::Mail.new
862
# mail.charset #=> nil
863
# mail.charset("US-ASCII") #=> "US-ASCII"
864
def charset( default = nil )
865
if h = @header['content-type']
866
h['charset'] or default
868
mime_version_charset || default
872
# some weird emails come with the charset specified in the mime-version header:
874
# #<TMail::MimeVersionHeader "1.0\n charset=\"gb2312\"">
876
def mime_version_charset
877
if header['mime-version'].inspect =~ /charset=('|\\")?([^\\"']+)/
882
# Destructively sets the character set used by this mail object to the passed string, you
883
# should note though that this does nothing to the mail body, just changes the header
884
# value, you will need to transliterate the body as well to match whatever you put
885
# in this header value if you are changing character sets.
889
# mail = TMail::Mail.new
890
# mail.charset #=> nil
891
# mail.charset = "UTF-8"
892
# mail.charset #=> "UTF-8"
895
if h = @header[ 'content-type' ]
898
store 'Content-Type', "text/plain; charset=#{str}"
904
# Returns the transfer encoding of the email. Returns nil if no encoding set or returns
905
# whatever default you pass as a parameter - note passing the parameter does NOT change
906
# the mail object in any way.
910
# mail = TMail::Mail.load("path_to/base64_encoded_email")
911
# mail.transfer_encoding #=> "base64"
913
# mail = TMail::Mail.new
914
# mail.transfer_encoding #=> nil
915
# mail.transfer_encoding("base64") #=> "base64"
916
def transfer_encoding( default = nil )
917
if h = @header['content-transfer-encoding']
918
h.encoding || default
924
# Destructively sets the transfer encoding of the mail object to the passed string, you
925
# should note though that this does nothing to the mail body, just changes the header
926
# value, you will need to encode or decode the body as well to match whatever you put
927
# in this header value.
931
# mail = TMail::Mail.new
932
# mail.transfer_encoding #=> nil
933
# mail.transfer_encoding = "base64"
934
# mail.transfer_encoding #=> "base64"
935
def transfer_encoding=( str )
936
set_string_attr 'Content-Transfer-Encoding', str
939
alias encoding transfer_encoding
940
alias encoding= transfer_encoding=
941
alias content_transfer_encoding transfer_encoding
942
alias content_transfer_encoding= transfer_encoding=
944
# Returns the content-disposition of the mail object, returns nil or the passed
945
# default value if given
949
# mail = TMail::Mail.load("path_to/raw_mail_with_attachment")
950
# mail.disposition #=> "attachment"
952
# mail = TMail::Mail.load("path_to/plain_simple_email")
953
# mail.disposition #=> nil
954
# mail.disposition(false) #=> false
955
def disposition( default = nil )
956
if h = @header['content-disposition']
957
h.disposition || default
963
alias content_disposition disposition
965
# Allows you to set the content-disposition of the mail object. Accepts a type
966
# and a hash of parameters.
970
# mail.set_disposition("attachment", {:filename => "test.rb"})
971
# mail.disposition #=> "attachment"
972
# mail['content-disposition'].to_s #=> "attachment; filename=test.rb"
973
def set_disposition( str, params = nil )
974
if h = @header['content-disposition']
978
store('Content-Disposition', str)
979
h = @header['content-disposition']
981
h.params.replace params if params
984
alias disposition= set_disposition
985
alias set_content_disposition set_disposition
986
alias content_disposition= set_disposition
988
# Returns the value of a parameter in an existing content-disposition header
992
# mail.set_disposition("attachment", {:filename => "test.rb"})
993
# mail['content-disposition'].to_s #=> "attachment; filename=test.rb"
994
# mail.disposition_param("filename") #=> "test.rb"
995
# mail.disposition_param("missing_param_key") #=> nil
996
# mail.disposition_param("missing_param_key", false) #=> false
997
# mail.disposition_param("missing_param_key", "Nothing to see here") #=> "Nothing to see here"
998
def disposition_param( name, default = nil )
999
if h = @header['content-disposition']
1006
# Convert the Mail object's body into a Base64 encoded email
1007
# returning the modified Mail object
1009
store 'Content-Transfer-Encoding', 'Base64'
1010
self.body = base64_encode
1013
# Return the result of encoding the TMail::Mail object body
1014
# without altering the current body
1016
Base64.folding_encode(self.body)
1019
# Convert the Mail object's body into a Base64 decoded email
1020
# returning the modified Mail object
1022
if /base64/i === self.transfer_encoding('')
1023
store 'Content-Transfer-Encoding', '8bit'
1024
self.body = base64_decode
1028
# Returns the result of decoding the TMail::Mail object body
1029
# without altering the current body
1031
Base64.decode(self.body, @config.strict_base64decode?)
1034
# Returns an array of each destination in the email message including to: cc: or bcc:
1038
# mail.to = "Mikel <mikel@lindsaar.net>"
1039
# mail.cc = "Trans <t@t.com>"
1040
# mail.bcc = "bob <bob@me.com>"
1041
# mail.destinations #=> ["mikel@lindsaar.net", "t@t.com", "bob@me.com"]
1042
def destinations( default = nil )
1044
%w( to cc bcc ).each do |nm|
1046
h.addrs.each {|i| ret.push i.address }
1049
ret.empty? ? default : ret
1052
# Yields a block of destination, yielding each as a string.
1053
# (from the destinations example)
1054
# mail.each_destination { |d| puts "#{d.class}: #{d}" }
1055
# String: mikel@lindsaar.net
1057
# String: bob@me.com
1058
def each_destination( &block )
1059
destinations([]).each do |i|
1068
alias each_dest each_destination
1070
# Returns an array of reply to addresses that the Mail object has,
1071
# or if the Mail message has no reply-to, returns an array of the
1072
# Mail objects from addresses. Else returns the default which can
1073
# either be passed as a parameter or defaults to nil
1076
# mail.from = "Mikel <mikel@lindsaar.net>"
1077
# mail.reply_to = nil
1078
# mail.reply_addresses #=> [""]
1080
def reply_addresses( default = nil )
1081
reply_to_addrs(nil) or from_addrs(nil) or default
1084
# Returns the "sender" field as an array -> useful to find out who to
1085
# send an error email to.
1086
def error_reply_addresses( default = nil )
1094
# Returns true if the Mail object is a multipart message
1096
main_type('').downcase == 'multipart'
1099
# Creates a new email in reply to self. Sets the In-Reply-To and
1100
# References headers for you automagically.
1103
# mail = TMail::Mail.load("my_email")
1104
# reply_email = mail.create_reply
1105
# reply_email.class #=> TMail::Mail
1106
# reply_email.references #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"]
1107
# reply_email.in_reply_to #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"]
1109
setup_reply create_empty_mail()
1112
# Creates a new email in reply to self. Sets the In-Reply-To and
1113
# References headers for you automagically.
1116
# mail = TMail::Mail.load("my_email")
1117
# forward_email = mail.create_forward
1118
# forward_email.class #=> TMail::Mail
1119
# forward_email.content_type #=> "multipart/mixed"
1120
# forward_email.body #=> "Attachment: (unnamed)"
1121
# forward_email.encoded #=> Returns the original email as a MIME attachment
1123
setup_forward create_empty_mail()
1129
def create_empty_mail
1130
self.class.new(StringPort.new(''), @config)
1133
def setup_reply( mail )
1134
if tmp = reply_addresses(nil)
1138
mid = message_id(nil)
1139
tmp = references(nil) || []
1141
mail.in_reply_to = [mid] if mid
1142
mail.references = tmp unless tmp.empty?
1143
mail.subject = 'Re: ' + subject('').sub(/\A(?:\[[^\]]+\])?(?:\s*Re:)*\s*/i, '')
1144
mail.mime_version = '1.0'
1148
def setup_forward( mail )
1149
m = Mail.new(StringPort.new(''))
1151
m.set_content_type 'message', 'rfc822'
1152
m.encoding = encoding('7bit')
1154
# call encoded to reparse the message
added
removed
lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb
