Class: TMail::Mail

Inherits:
Object show all
Includes:
StrategyInterface, TextUtils
Defined in:
lib/tmail/mail.rb,
lib/tmail/net.rb,
lib/tmail/quoting.rb,
lib/tmail/obsolete.rb,
lib/tmail/obsolete.rb,
lib/tmail/interface.rb,
lib/tmail/attachments.rb

Overview

:nodoc:

Constant Summary collapse

NOSEND_FIELDS = 
%w(
  received
  bcc
)
ALLOW_MULTIPLE = 
{
  'received'          => true,
  'resent-date'       => true,
  'resent-from'       => true,
  'resent-sender'     => true,
  'resent-to'         => true,
  'resent-cc'         => true,
  'resent-bcc'        => true,
  'resent-message-id' => true,
  'comments'          => true,
  'keywords'          => true
}
USE_ARRAY = 
ALLOW_MULTIPLE
FIELD_ORDER = 
%w(
  return-path received
  resent-date resent-from resent-sender resent-to
  resent-cc resent-bcc resent-message-id
  date from sender reply-to to cc bcc
  message-id in-reply-to references
  subject comments keywords
  mime-version content-type content-transfer-encoding
  content-disposition content-description
)

Constants included from TextUtils

TextUtils::ATOM_UNSAFE, TextUtils::CONTROL_CHAR, TextUtils::MESSAGE_ID, TextUtils::MIME_ENCODED, TextUtils::MONTH, TextUtils::NKF_FLAGS, TextUtils::PHRASE_UNSAFE, TextUtils::RFC2231_ENCODED, TextUtils::TOKEN_UNSAFE, TextUtils::WDAY, TextUtils::ZONESTR_TABLE

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from TextUtils

#atom_safe?, #decode_RFC2231, #decode_params, #join_domain, #message_id?, #mime_encoded?, #quote_atom, #quote_boundary, #quote_phrase, #quote_token, #quote_unquoted_bencode, #quote_unquoted_name, #time2str, #timezone_string_to_unixtime, #to_kcode, #token_safe?, #unquote

Methods included from StrategyInterface

#accept_strategy, create_dest, #decoded, #encoded

Constructor Details

#initialize(port = nil, conf = DEFAULT_CONFIG) ⇒ Mail

:nodoc:



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/tmail/mail.rb', line 128

def initialize( port = nil, conf = DEFAULT_CONFIG ) #:nodoc:
  @port = port || StringPort.new
  @config = Config.to_config(conf)

  @header      = {}
  @body_port   = nil
  @body_parsed = false
  @epilogue    = ''
  @parts       = []

  @port.ropen {|f|
      parse_header f
      parse_body f unless @port.reproducible?
  }
end

Instance Attribute Details

#port ⇒ Object (readonly)

Provides access to the port this email is using to hold it’s data

Example:

mail = TMail::Mail.parse(email_string)
mail.port
#=> #<TMail::StringPort:id=0xa2c952>



150
151
152
 
# File 'lib/tmail/mail.rb', line 150

def port
  @port
end

Class Method Details

.boundary ⇒ Object 



123
124
125
 
# File 'lib/tmail/obsolete.rb', line 123

def Mail.boundary
  ::TMail.new_boundary
end

.load(fname) ⇒ Object Also known as: load_from, loadfrom

Opens an email that has been saved out as a file by itself.

This function will read a file non-destructively and then parse the contents and return a TMail::Mail object.

Does not handle multiple email mailboxes (like a unix mbox) for that use the TMail::UNIXMbox class.

Example:

mail = TMail::Mail.load('filename')



98
99
100
 
# File 'lib/tmail/mail.rb', line 98

def load( fname )
  new(FilePort.new(fname))
end

.msgid ⇒ Object 



127
128
129
 
# File 'lib/tmail/obsolete.rb', line 127

def Mail.msgid
  ::TMail.new_message_id
end

.parse(str) ⇒ Object

Parses an email from the supplied string and returns a TMail::Mail object.

Example:

require 'rubygems'; require 'tmail'
email_string =<<HEREDOC
To: [email protected]
From: [email protected]
Subject: This is a short Email

Hello there Mikel!

HEREDOC
mail = TMail::Mail.parse(email_string)
#=> #<TMail::Mail port=#<TMail::StringPort:id=0xa30ac0> bodyport=nil>
mail.body
#=> "Hello there Mikel!\n\n"



122
123
124
 
# File 'lib/tmail/mail.rb', line 122

def parse( str )
  new(StringPort.new(str))
end

Instance Method Details

#[](key) ⇒ Object Also known as: fetch

Returns a TMail::AddressHeader object of the field you are querying. Examples:

@mail['from']  #=> #<TMail::AddressHeader "[email protected]">
@mail['to']    #=> #<TMail::AddressHeader "[email protected]">

You can get the string value of this by passing “to_s” to the query: Example:

@mail['to'].to_s #=> "[email protected]"



247
248
249
 
# File 'lib/tmail/mail.rb', line 247

def []( key )
  @header[key.downcase]
end

#[]=(key, val) ⇒ Object Also known as: store

Allows you to set or delete TMail header objects at will. Examples:

@mail = TMail::Mail.new
@mail['to'].to_s       # => '[email protected]'
@mail['to'] = '[email protected]'
@mail['to'].to_s       # => '[email protected]'
@mail.encoded          # => "To: [email protected]\r\n\r\n"
@mail['to'] = nil
@mail['to'].to_s       # => nil
@mail.encoded          # => "\r\n"

Note: setting mail[] = nil actually deletes the header field in question from the object, it does not just set the value of the hash to nil



270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/tmail/mail.rb', line 270

def []=( key, val )
  dkey = key.downcase

  if val.nil?
    @header.delete dkey
    return nil
  end

  case val
  when String
    header = new_hf(key, val)
  when HeaderField
    ;
  when Array
    ALLOW_MULTIPLE.include? dkey or
            raise ArgumentError, "#{key}: Header must not be multiple"
    @header[dkey] = val
    return val
  else
    header = new_hf(key, val.to_s)
  end
  if ALLOW_MULTIPLE.include? dkey
    (@header[dkey] ||= []).push header
  else
    @header[dkey] = header
  end

  val
end

#accept(strategy) ⇒ Object 



169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/tmail/mail.rb', line 169

def accept( strategy )
  with_multipart_encoding(strategy) {
      ordered_each do |name, field|
        next if field.empty?
        strategy.header_name canonical(name)
        field.accept strategy
        strategy.puts
      end
      strategy.puts
      body_port().ropen {|r|
          strategy.write r.read
      }
  }
end

#add_date ⇒ Object 



86
87
88
 
# File 'lib/tmail/net.rb', line 86

def add_date
  self.date = Time.now
end

#add_message_id(fqdn = nil) ⇒ Object 



80
81
82
83
84
 
# File 'lib/tmail/net.rb', line 80

def add_message_id( fqdn = nil )
  unless @message_id_enforced
    self.message_id = ::TMail::new_message_id(fqdn)
  end
end

#attachment?(part) ⇒ Boolean

Returns:

  • (Boolean) 


31
32
33
 
# File 'lib/tmail/attachments.rb', line 31

def attachment?(part)
  part.disposition_is_attachment? || (!part.content_type.nil? && !part.text_content_type?) unless part.multipart?
end

#attachments ⇒ Object 



35
36
37
38
39
40
41
 
# File 'lib/tmail/attachments.rb', line 35

def attachments
  if multipart?
    parts.collect { |part| attachment(part) }.flatten.compact
  elsif attachment?(self)
    [attachment(self)]
  end
end

#base64_decode ⇒ Object

Returns the result of decoding the TMail::Mail object body without altering the current body



1030
1031
1032
 
# File 'lib/tmail/interface.rb', line 1030

def base64_decode
  Base64.decode(self.body, @config.strict_base64decode?)
end

#base64_decode! ⇒ Object

Convert the Mail object’s body into a Base64 decoded email returning the modified Mail object



1021
1022
1023
1024
1025
1026
 
# File 'lib/tmail/interface.rb', line 1021

def base64_decode!
  if /base64/i === self.transfer_encoding('')
    store 'Content-Transfer-Encoding', '8bit'
    self.body = base64_decode
  end
end

#base64_encode ⇒ Object

Return the result of encoding the TMail::Mail object body without altering the current body



1015
1016
1017
 
# File 'lib/tmail/interface.rb', line 1015

def base64_encode
  Base64.folding_encode(self.body)
end

#base64_encode! ⇒ Object

Convert the Mail object’s body into a Base64 encoded email returning the modified Mail object



1008
1009
1010
1011
 
# File 'lib/tmail/interface.rb', line 1008

def base64_encode!
  store 'Content-Transfer-Encoding', 'Base64'
  self.body = base64_encode
end

#bcc(default = nil) ⇒ Object

Returns who the email bcc’d as an Array of email addresses as opposed to an Array of TMail::Address objects which is what Mail#to_addrs returns

Example:

mail = TMail::Mail.new
mail.bcc = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.bcc #=>  ["[email protected]", "[email protected]"]



292
293
294
 
# File 'lib/tmail/interface.rb', line 292

def bcc( default = nil )
  addrs2specs(bcc_addrs(nil)) || default
end

#bcc=(*strs) ⇒ Object

Destructively sets the “Bcc:” field to the passed array of strings (which should be valid email addresses)

Example:

mail = TMail::Mail.new
mail.bcc = ["[email protected]", "Mikel <[email protected]>"]
mail.bcc #=>  ["[email protected]", "[email protected]"]
mail['bcc'].to_s #=> "[email protected], Mikel <[email protected]>"



331
332
333
 
# File 'lib/tmail/interface.rb', line 331

def bcc=( *strs )
  set_string_array_attr 'Bcc', strs
end

#bcc_addrs(default = nil) ⇒ Object

Return a TMail::Addresses instance for each entry in the “Bcc:” field of the mail object header.

If the “Bcc:” field does not exist, will return nil by default or the value you pass as the optional parameter.

Example:

mail = TMail::Mail.new
mail.bcc_addrs #=> nil
mail.bcc_addrs([]) #=> []
mail.bcc = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.bcc_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



210
211
212
213
214
215
216
 
# File 'lib/tmail/interface.rb', line 210

def bcc_addrs( default = nil )
  if h = @header['bcc']
    h.addrs
  else
    default
  end
end

#bcc_addrs=(arg) ⇒ Object

Destructively set the to field of the “Bcc:” header to equal the passed in string.

TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.

Example:

mail = TMail::Mail.new
mail.bcc = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.bcc_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



256
257
258
 
# File 'lib/tmail/interface.rb', line 256

def bcc_addrs=( arg )
  set_addrfield 'bcc', arg
end

#body(to_charset = 'utf-8', &block) ⇒ Object 



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/tmail/quoting.rb', line 36

def body(to_charset = 'utf-8', &block)
  attachment_presenter = block || Proc.new { |file_name| "Attachment: #{file_name}\n" }

  if multipart?
    parts.collect { |part|
      header = part["content-type"]

      if part.multipart?
        part.body(to_charset, &attachment_presenter)
      elsif header.nil?
        ""
      elsif !attachment?(part)
        part.unquoted_body(to_charset)
      else
        attachment_presenter.call(header["name"] || "(unnamed)")
      end
    }.join
  else
    unquoted_body(to_charset)
  end
end

#body=(str) ⇒ Object 



463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
 
# File 'lib/tmail/mail.rb', line 463

def body=( str )
  # Sets the body of the email to a new (encoded) string.
  # 
  # We also reparses the email if the body is ever reassigned, this is a performance hit, however when
  # you assign the body, you usually want to be able to make sure that you can access the attachments etc.
  # 
  # Usage:
  # 
  #  mail.body = "Hello, this is\nthe body text"
  #  # => "Hello, this is\nthe body"
  #  mail.body
  #  # => "Hello, this is\nthe body"
  @body_parsed = false
  parse_body(StringInput.new(str))
  parse_body
  @body_port.wopen {|f| f.write str }
  str
end

#body_port ⇒ Object 



445
446
447
448
 
# File 'lib/tmail/mail.rb', line 445

def body_port
  parse_body
  @body_port
end

#cc(default = nil) ⇒ Object

Returns who the email cc’d as an Array of email addresses as opposed to an Array of TMail::Address objects which is what Mail#to_addrs returns

Example:

mail = TMail::Mail.new
mail.cc = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.cc #=>  ["[email protected]", "[email protected]"]



280
281
282
 
# File 'lib/tmail/interface.rb', line 280

def cc( default = nil )
  addrs2specs(cc_addrs(nil)) || default
end

#cc=(*strs) ⇒ Object

Destructively sets the “Cc:” field to the passed array of strings (which should be valid email addresses)

Example:

mail = TMail::Mail.new
mail.cc = ["[email protected]", "Mikel <[email protected]>"]
mail.cc #=>  ["[email protected]", "[email protected]"]
mail['cc'].to_s #=> "[email protected], Mikel <[email protected]>"



318
319
320
 
# File 'lib/tmail/interface.rb', line 318

def cc=( *strs )
  set_string_array_attr 'Cc', strs
end

#cc_addrs(default = nil) ⇒ Object

Return a TMail::Addresses instance for each entry in the “Cc:” field of the mail object header.

If the “Cc:” field does not exist, will return nil by default or the value you pass as the optional parameter.

Example:

mail = TMail::Mail.new
mail.cc_addrs #=> nil
mail.cc_addrs([]) #=> []
mail.cc = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.cc_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



190
191
192
193
194
195
196
 
# File 'lib/tmail/interface.rb', line 190

def cc_addrs( default = nil )
  if h = @header['cc']
    h.addrs
  else
    default
  end
end

#cc_addrs=(arg) ⇒ Object

Destructively set the to field of the “Cc:” header to equal the passed in string.

TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.

Example:

mail = TMail::Mail.new
mail.cc = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.cc_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



242
243
244
 
# File 'lib/tmail/interface.rb', line 242

def cc_addrs=( arg )
  set_addrfield 'cc', arg
end

#charset(default = nil) ⇒ Object

Returns the character set of the email. Returns nil if no encoding set or returns whatever default you pass as a parameter - note passing the parameter does NOT change the mail object in any way.

Example:

mail = TMail::Mail.load("path_to/utf8_email")
mail.charset #=> "UTF-8"

mail = TMail::Mail.new
mail.charset #=> nil
mail.charset("US-ASCII") #=> "US-ASCII"



864
865
866
867
868
869
870
 
# File 'lib/tmail/interface.rb', line 864

def charset( default = nil )
  if h = @header['content-type']
    h['charset'] or default
  else
    mime_version_charset || default
  end
end

#charset=(str) ⇒ Object

Destructively sets the character set used by this mail object to the passed string, you should note though that this does nothing to the mail body, just changes the header value, you will need to transliterate the body as well to match whatever you put in this header value if you are changing character sets.

Example:

mail = TMail::Mail.new
mail.charset #=> nil
mail.charset = "UTF-8"
mail.charset #=> "UTF-8"



893
894
895
896
897
898
899
900
901
902
 
# File 'lib/tmail/interface.rb', line 893

def charset=( str )
  if str
    if h = @header[ 'content-type' ]
      h['charset'] = str
    else
      store 'Content-Type', "text/plain; charset=#{str}"
    end
  end
  str
end

#clear ⇒ Object 



352
353
354
 
# File 'lib/tmail/mail.rb', line 352

def clear
  @header.clear
end

#content_type(default = nil) ⇒ Object

Returns the current “Content-Type” of the mail instance.

If the content_type field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.

Example:

mail = TMail::Mail.new
mail.content_type #=> nil
mail.content_type([]) #=> []
mail = TMail::Mail.load("../test/fixtures/raw_email")
mail.content_type #=> "text/plain"



747
748
749
750
751
752
753
 
# File 'lib/tmail/interface.rb', line 747

def content_type( default = nil )
  if h = @header['content-type']
    h.content_type || default
  else
    default
  end
end

#content_type_is_text? ⇒ Boolean

Returns true if this part’s content main type is text, else returns false. By main type is meant “text/plain” is text. “text/html” is text

Returns:

  • (Boolean) 


513
514
515
 
# File 'lib/tmail/mail.rb', line 513

def content_type_is_text?
  self.header['content-type'] && (self.header['content-type'].main_type != "text")
end

#create_forward ⇒ Object

Creates a new email in reply to self. Sets the In-Reply-To and References headers for you automagically.

Example:

mail = TMail::Mail.load("my_email")
forward_email = mail.create_forward
forward_email.class         #=> TMail::Mail
forward_email.content_type  #=> "multipart/mixed"
forward_email.body          #=> "Attachment: (unnamed)"
forward_email.encoded       #=> Returns the original email as a MIME attachment



1122
1123
1124
 
# File 'lib/tmail/interface.rb', line 1122

def create_forward
  setup_forward create_empty_mail()
end

#create_reply ⇒ Object

Creates a new email in reply to self. Sets the In-Reply-To and References headers for you automagically.

Example:

mail = TMail::Mail.load("my_email")
reply_email = mail.create_reply
reply_email.class         #=> TMail::Mail
reply_email.references  #=> ["<[email protected]>"]
reply_email.in_reply_to #=> ["<[email protected]>"]



1108
1109
1110
 
# File 'lib/tmail/interface.rb', line 1108

def create_reply
  setup_reply create_empty_mail()
end

#date(default = nil) ⇒ Object

Returns the date of the email message as per the “date” header value or returns nil by default (if no date field exists).

You can also pass whatever default you want into this method and it will return that instead of nil if there is no date already set.



115
116
117
118
119
120
121
 
# File 'lib/tmail/interface.rb', line 115

def date( default = nil )
  if h = @header['date']
    h.date
  else
    default
  end
end

#date=(time) ⇒ Object

Destructively sets the date of the mail object with the passed Time instance, returns a Time instance set to the date/time of the mail

Example:

now = Time.now
mail.date = now
mail.date #=> Sat Nov 03 18:47:50 +1100 2007
mail.date.class #=> Time



132
133
134
135
136
137
138
139
 
# File 'lib/tmail/interface.rb', line 132

def date=( time )
  if time
    store 'Date', time2str(time)
  else
    @header.delete 'date'
  end
  time
end

#delete(key) ⇒ Object 



356
357
358
 
# File 'lib/tmail/mail.rb', line 356

def delete( key )
  @header.delete key.downcase
end

#delete_if ⇒ Object 



360
361
362
363
364
365
366
367
368
369
 
# File 'lib/tmail/mail.rb', line 360

def delete_if
  @header.delete_if do |key,val|
    if Array === val
      val.delete_if {|v| yield key, v }
      val.empty?
    else
      yield key, val
    end
  end
end

#delete_no_send_fields ⇒ Object 



73
74
75
76
77
78
 
# File 'lib/tmail/net.rb', line 73

def delete_no_send_fields
  NOSEND_FIELDS.each do |nm|
    delete nm
  end
  delete_if {|n,v| v.empty? }
end

#destinations(default = nil) ⇒ Object

Returns an array of each destination in the email message including to: cc: or bcc:

Example:

mail.to = "Mikel <[email protected]>"
mail.cc = "Trans <[email protected]>"
mail.bcc = "bob <[email protected]>"
mail.destinations #=> ["[email protected]", "[email protected]", "[email protected]"]



1042
1043
1044
1045
1046
1047
1048
1049
1050
 
# File 'lib/tmail/interface.rb', line 1042

def destinations( default = nil )
  ret = []
  %w( to cc bcc ).each do |nm|
    if h = @header[nm]
      h.addrs.each {|i| ret.push i.address }
    end
  end
  ret.empty? ? default : ret
end

#disposition(default = nil) ⇒ Object Also known as: content_disposition

Returns the content-disposition of the mail object, returns nil or the passed default value if given

Example:

mail = TMail::Mail.load("path_to/raw_mail_with_attachment") 
mail.disposition #=> "attachment"

mail = TMail::Mail.load("path_to/plain_simple_email")
mail.disposition #=> nil
mail.disposition(false) #=> false



955
956
957
958
959
960
961
 
# File 'lib/tmail/interface.rb', line 955

def disposition( default = nil )
  if h = @header['content-disposition']
    h.disposition || default
  else
    default
  end
end

#disposition_is_attachment? ⇒ Boolean

Returns true if the content type of this part of the email is a disposition attachment

Returns:

  • (Boolean) 


507
508
509
 
# File 'lib/tmail/mail.rb', line 507

def disposition_is_attachment?
  (self['content-disposition'] && self['content-disposition'].disposition == "attachment")
end

#disposition_param(name, default = nil) ⇒ Object

Returns the value of a parameter in an existing content-disposition header

Example:

mail.set_disposition("attachment", {:filename => "test.rb"})
mail['content-disposition'].to_s #=> "attachment; filename=test.rb"
mail.disposition_param("filename") #=> "test.rb"
mail.disposition_param("missing_param_key") #=> nil
mail.disposition_param("missing_param_key", false) #=> false
mail.disposition_param("missing_param_key", "Nothing to see here") #=> "Nothing to see here"



998
999
1000
1001
1002
1003
1004
 
# File 'lib/tmail/interface.rb', line 998

def disposition_param( name, default = nil )
  if h = @header['content-disposition']
    h[name] || default
  else
    default
  end
end

#each(&block) ⇒ Object 



450
451
452
 
# File 'lib/tmail/mail.rb', line 450

def each( &block )
  body_port().ropen {|f| f.each(&block) }
end

#each_destination(&block) ⇒ Object Also known as: each_dest

Yields a block of destination, yielding each as a string.

(from the destinations example)
mail.each_destination { |d| puts "#{d.class}: #{d}" }
String: [email protected]
String: [email protected]
String: [email protected]



1058
1059
1060
1061
1062
1063
1064
1065
1066
 
# File 'lib/tmail/interface.rb', line 1058

def each_destination( &block )
  destinations([]).each do |i|
    if Address === i
      yield i
    else
      i.each(&block)
    end
  end
end

#each_field(&block) ⇒ Object Also known as: each_value 



323
324
325
 
# File 'lib/tmail/mail.rb', line 323

def each_field( &block )
  @header.values.flatten.each(&block)
end

#each_header ⇒ Object Also known as: each_pair

Allows you to loop through each header in the TMail::Mail object in a block Example:

@mail['to'] = '[email protected]'
@mail['from'] = '[email protected]'
@mail.each_header { |k,v| puts "#{k} = #{v}" }
# => from = [email protected]
# => to = [email protected]



309
310
311
312
313
 
# File 'lib/tmail/mail.rb', line 309

def each_header
  @header.each do |key, val|
    [val].flatten.each {|v| yield key, v }
  end
end

#each_header_name(&block) ⇒ Object Also known as: each_key 



317
318
319
 
# File 'lib/tmail/mail.rb', line 317

def each_header_name( &block )
  @header.each_key(&block)
end

#each_part(&block) ⇒ Object 



501
502
503
 
# File 'lib/tmail/mail.rb', line 501

def each_part( &block )
  parts().each(&block)
end

#enforced_message_id=(str) ⇒ Object

Destructively sets the message ID of the mail object instance to the passed in string and also guarantees that calling #ready_to_send will not destroy what you set as the message_id

Example:

mail = TMail::Mail.new
mail.message_id = "<[email protected]>"
mail.message_id #=> "<[email protected]>"
mail.ready_to_send
mail.message_id #=> "<[email protected]>"



626
627
628
629
 
# File 'lib/tmail/interface.rb', line 626

def enforced_message_id=( str )
  @message_id_enforced = true
  self.message_id = ( str )
end

#epilogue ⇒ Object 



485
486
487
488
 
# File 'lib/tmail/mail.rb', line 485

def epilogue
  parse_body
  @epilogue.dup
end

#epilogue=(str) ⇒ Object 



490
491
492
493
494
 
# File 'lib/tmail/mail.rb', line 490

def epilogue=( str )
  parse_body
  @epilogue = str
  str
end

#error_reply_addresses(default = nil) ⇒ Object

Returns the “sender” field as an array -> useful to find out who to send an error email to.



1086
1087
1088
1089
1090
1091
1092
 
# File 'lib/tmail/interface.rb', line 1086

def error_reply_addresses( default = nil )
  if s = sender(nil)
    [s]
  else
    from_addrs(default)
  end
end

#friendly_from(default = nil) ⇒ Object

Returns the “friendly” human readable part of the address

Example:

mail = TMail::Mail.new
mail.from = "Mikel Lindsaar <[email protected]>"
mail.friendly_from #=> "Mikel Lindsaar"



403
404
405
406
407
408
409
410
 
# File 'lib/tmail/interface.rb', line 403

def friendly_from( default = nil )
  h = @header['from']
  a, = h.addrs
  return default unless a
  return a.phrase if a.phrase
  return h.comments.join(' ') unless h.comments.empty?
  a.spec
end

#from(default = nil) ⇒ Object

Returns who the email is from as an Array of email address strings instead to an Array of TMail::Address objects which is what Mail#from_addrs returns

Example:

mail = TMail::Mail.new
mail.from = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.from #=>  ["[email protected]", "[email protected]"]



379
380
381
 
# File 'lib/tmail/interface.rb', line 379

def from( default = nil )
  addrs2specs(from_addrs(nil)) || default
end

#from=(*strs) ⇒ Object

Destructively sets the “From:” field to the passed array of strings (which should be valid email addresses)

Example:

mail = TMail::Mail.new
mail.from = ["[email protected]", "Mikel <[email protected]>"]
mail.from #=>  ["[email protected]", "[email protected]"]
mail['from'].to_s #=> "[email protected], Mikel <[email protected]>"



392
393
394
 
# File 'lib/tmail/interface.rb', line 392

def from=( *strs )
  set_string_array_attr 'From', strs
end

#from_addr(default = nil) ⇒ Object 



57
58
59
60
 
# File 'lib/tmail/obsolete.rb', line 57

def from_addr( default = nil )
  addr, = from_addrs(nil)
  addr || default
end

#from_address(default = nil) ⇒ Object 



62
63
64
65
66
67
68
 
# File 'lib/tmail/obsolete.rb', line 62

def from_address( default = nil )
  if a = from_addr(nil)
    a.spec
  else
    default
  end
end

#from_address= ⇒ Object 



70
 
# File 'lib/tmail/obsolete.rb', line 70

alias from_address= from_addrs=

#from_addrs(default = nil) ⇒ Object

Return a TMail::Addresses instance for each entry in the “From:” field of the mail object header.

If the “From:” field does not exist, will return nil by default or the value you pass as the optional parameter.

Example:

mail = TMail::Mail.new
mail.from_addrs #=> nil
mail.from_addrs([]) #=> []
mail.from = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.from_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



349
350
351
352
353
354
355
 
# File 'lib/tmail/interface.rb', line 349

def from_addrs( default = nil )
  if h = @header['from']
    h.addrs
  else
    default
  end
end

#from_addrs=(arg) ⇒ Object

Destructively set the to value of the “From:” header to equal the passed in string.

TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.

Example:

mail = TMail::Mail.new
mail.from_addrs = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.from_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



367
368
369
 
# File 'lib/tmail/interface.rb', line 367

def from_addrs=( arg )
  set_addrfield 'from', arg
end

#from_phrase(default = nil) ⇒ Object 



72
73
74
75
76
77
78
 
# File 'lib/tmail/obsolete.rb', line 72

def from_phrase( default = nil )
  if a = from_addr(nil)
    a.phrase
  else
    default
  end
end

#has_attachments? ⇒ Boolean

Returns:

  • (Boolean) 


17
18
19
 
# File 'lib/tmail/attachments.rb', line 17

def has_attachments?
  attachment?(self) || multipart? && parts.any? { |part| attachment?(part) }
end

#header ⇒ Object 



235
236
237
 
# File 'lib/tmail/mail.rb', line 235

def header
  @header.dup
end

#header_string(name, default = nil) ⇒ Object

Allows you to query the mail object with a string to get the contents of the field you want.

Returns a string of the exact contents of the field

mail.from = "mikel <[email protected]>"
mail.header_string("From") #=> "mikel <[email protected]>"



49
50
51
52
 
# File 'lib/tmail/interface.rb', line 49

def header_string( name, default = nil )
  h = @header[name.downcase] or return default
  h.to_s
end

#in_reply_to(default = nil) ⇒ Object

Returns the “In-Reply-To:” field contents as an array of this mail instance if it exists

If the in_reply_to field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.

Example:

mail = TMail::Mail.new
mail.in_reply_to #=> nil
mail.in_reply_to([]) #=> []
TMail::Mail.load("../test/fixtures/raw_email_reply")
mail.in_reply_to #=> ["<[email protected]>"]



643
644
645
646
647
648
649
 
# File 'lib/tmail/interface.rb', line 643

def in_reply_to( default = nil )
  if h = @header['in-reply-to']
    h.ids
  else
    default
  end
end

#in_reply_to=(*idstrs) ⇒ Object

Destructively sets the value of the “In-Reply-To:” field of an email.

Accepts an array of a single string of a message id

Example: 

mail = TMail::Mail.new
mail.in_reply_to = ["<[email protected]>"]
mail.in_reply_to #=> ["<[email protected]>"]



660
661
662
 
# File 'lib/tmail/interface.rb', line 660

def in_reply_to=( *idstrs )
  set_string_array_attr 'In-Reply-To', idstrs
end

#inline_attachment?(part) ⇒ Boolean

Returns:

  • (Boolean) 


27
28
29
 
# File 'lib/tmail/attachments.rb', line 27

def inline_attachment?(part)
  part['content-id'] || (part['content-disposition'] && part['content-disposition'].disposition == 'inline' && !part.text_content_type?)
end

#inspect ⇒ Object 



152
153
154
 
# File 'lib/tmail/mail.rb', line 152

def inspect
  "\#<#{self.class} port=#{@port.inspect} bodyport=#{@body_port.inspect}>"
end

#key?(key) ⇒ Boolean Also known as: include?, has_key?

Returns:

  • (Boolean) 


375
376
377
 
# File 'lib/tmail/mail.rb', line 375

def key?( key )
  @header.key? key.downcase
end

#keys ⇒ Object 



371
372
373
 
# File 'lib/tmail/mail.rb', line 371

def keys
  @header.keys
end

#main_type(default = nil) ⇒ Object

Returns the current main type of the “Content-Type” of the mail instance.

If the content_type field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.

Example:

mail = TMail::Mail.new
mail.main_type #=> nil
mail.main_type([]) #=> []
mail = TMail::Mail.load("../test/fixtures/raw_email")
mail.main_type #=> "text"



767
768
769
770
771
772
773
 
# File 'lib/tmail/interface.rb', line 767

def main_type( default = nil )
  if h = @header['content-type']
    h.main_type || default
  else
    default
  end
end

#message_id(default = nil) ⇒ Object

Returns the message ID for this mail object instance.

If the message_id field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.

Example:

mail = TMail::Mail.new
mail.message_id #=> nil
mail.message_id(TMail.new_message_id) #=> "<[email protected]>"
mail.message_id = TMail.new_message_id
mail.message_id #=> "<[email protected]>"



585
586
587
588
589
590
591
 
# File 'lib/tmail/interface.rb', line 585

def message_id( default = nil )
  if h = @header['message-id']
    h.id || default
  else
    default
  end
end

#message_id=(str) ⇒ Object

Destructively sets the message ID of the mail object instance to the passed in string

Invalid message IDs are ignored (silently, unless configured otherwise) and result in a nil message ID. Left and right angle brackets are required.

Be warned however, that calling mail.ready_to_send will overwrite whatever value you have in this field with an automatically generated unique value.

If you really want to set your own message ID and know what you are doing per the various RFCs, you can do so with the enforced_message_id= command

Example:

mail = TMail::Mail.new
mail.message_id = "<[email protected]>"
mail.message_id #=> "<[email protected]>"
mail.message_id = "this_is_my_badly_formatted_message_id"
mail.message_id #=> nil



611
612
613
 
# File 'lib/tmail/interface.rb', line 611

def message_id=( str )
  set_string_attr 'Message-Id', str
end

#mime_encode ⇒ Object 



90
91
92
93
94
95
96
 
# File 'lib/tmail/net.rb', line 90

def mime_encode
  if parts.empty?
    mime_encode_singlepart
  else
    mime_encode_multipart true
  end
end

#mime_encode_binary(body) ⇒ Object 



114
115
116
117
118
 
# File 'lib/tmail/net.rb', line 114

def mime_encode_binary( body )
  self.body = [body].pack('m')
  self.set_content_type 'application', 'octet-stream'
  self.encoding = 'Base64'
end

#mime_encode_multipart(top = true) ⇒ Object 



120
121
122
123
124
125
126
127
128
 
# File 'lib/tmail/net.rb', line 120

def mime_encode_multipart( top = true )
  self.mime_version = '1.0' if top
  self.set_content_type 'multipart', 'mixed'
  e = encoding(nil)
  if e and not /\A(?:7bit|8bit|binary)\z/i === e
    raise ArgumentError,
          'using C.T.Encoding with multipart mail is not permitted'
  end
end

#mime_encode_singlepart ⇒ Object 



98
99
100
101
102
103
104
105
106
 
# File 'lib/tmail/net.rb', line 98

def mime_encode_singlepart
  self.mime_version = '1.0'
  b = body
  if NKF.guess(b) != NKF::BINARY
    mime_encode_text b
  else
    mime_encode_binary b
  end
end

#mime_encode_text(body) ⇒ Object 



108
109
110
111
112
 
# File 'lib/tmail/net.rb', line 108

def mime_encode_text( body )
  self.body = NKF.nkf('-j -m0', body)
  self.set_content_type 'text', 'plain', {'charset' => 'iso-2022-jp'}
  self.encoding = '7bit'
end

#mime_version(default = nil) ⇒ Object

Returns the listed MIME version of this email from the “Mime-Version:” header field

If the mime_version field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.

Example:

mail = TMail::Mail.new
mail.mime_version #=> nil
mail.mime_version([]) #=> []
mail = TMail::Mail.load("../test/fixtures/raw_email")
mail.mime_version #=> "1.0"



713
714
715
716
717
718
719
 
# File 'lib/tmail/interface.rb', line 713

def mime_version( default = nil )
  if h = @header['mime-version']
    h.version || default
  else
    default
  end
end

#mime_version=(m, opt = nil) ⇒ Object 



721
722
723
724
725
726
727
728
729
730
731
732
733
 
# File 'lib/tmail/interface.rb', line 721

def mime_version=( m, opt = nil )
  if opt
    if h = @header['mime-version']
      h.major = m
      h.minor = opt
    else
      store 'Mime-Version', "#{m}.#{opt}"
    end
  else
    store 'Mime-Version', m
  end
  m
end

#mime_version_charset ⇒ Object

some weird emails come with the charset specified in the mime-version header:

#<TMail::MimeVersionHeader "1.0\n charset=\"gb2312\"">



876
877
878
879
880
 
# File 'lib/tmail/interface.rb', line 876

def mime_version_charset
  if header['mime-version'].inspect =~ /charset=('|\\")?([^\\"']+)/
    $2
  end
end

#msgid ⇒ Object 



80
 
# File 'lib/tmail/obsolete.rb', line 80

alias msgid  message_id

#msgid= ⇒ Object 



81
 
# File 'lib/tmail/obsolete.rb', line 81

alias msgid= message_id=

#multipart? ⇒ Boolean

Returns true if the Mail object is a multipart message

Returns:

  • (Boolean) 


1095
1096
1097
 
# File 'lib/tmail/interface.rb', line 1095

def multipart?
  main_type('').downcase == 'multipart'
end

#ordered_each ⇒ Object 



340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/tmail/mail.rb', line 340

def ordered_each
  list = @header.keys
  FIELD_ORDER.each do |name|
    if list.delete(name)
      [@header[name]].flatten.each {|v| yield name, v }
    end
  end
  list.each do |name|
    [@header[name]].flatten.each {|v| yield name, v }
  end
end

#parts ⇒ Object 



496
497
498
499
 
# File 'lib/tmail/mail.rb', line 496

def parts
  parse_body
  @parts
end

#quoted_body ⇒ Object Also known as: preamble 



454
455
456
 
# File 'lib/tmail/mail.rb', line 454

def quoted_body
  body_port.ropen {|f| return f.read }
end

#quoted_body=(str) ⇒ Object Also known as: preamble= 



458
459
460
461
 
# File 'lib/tmail/mail.rb', line 458

def quoted_body= str
  body_port.wopen { |f| f.write str }
  str
end

#ready_to_send ⇒ Object 



62
63
64
65
66
 
# File 'lib/tmail/net.rb', line 62

def ready_to_send
  delete_no_send_fields
  add_message_id
  add_date
end

#references(default = nil) ⇒ Object

Returns the references of this email (prior messages relating to this message) as an array of message ID strings. Useful when you are trying to thread an email.

If the references field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.

Example:

mail = TMail::Mail.new
mail.references #=> nil
mail.references([]) #=> []
mail = TMail::Mail.load("../test/fixtures/raw_email_reply")
mail.references #=> ["<[email protected]>", "<[email protected]>"]



678
679
680
681
682
683
684
 
# File 'lib/tmail/interface.rb', line 678

def references( default = nil )
  if h = @header['references']
    h.refs
  else
    default
  end
end

#references=(*strs) ⇒ Object

Destructively sets the value of the “References:” field of an email.

Accepts an array of strings of message IDs

Example: 

mail = TMail::Mail.new
mail.references = ["<[email protected]>"]
mail.references #=> ["<[email protected]>"]



695
696
697
 
# File 'lib/tmail/interface.rb', line 695

def references=( *strs )
  set_string_array_attr 'References', strs
end

#reply_addresses(default = nil) ⇒ Object

Returns an array of reply to addresses that the Mail object has, or if the Mail message has no reply-to, returns an array of the Mail objects from addresses. Else returns the default which can either be passed as a parameter or defaults to nil

Example:

mail.from = "Mikel <[email protected]>"
mail.reply_to = nil
mail.reply_addresses #=> [""]



1080
1081
1082
 
# File 'lib/tmail/interface.rb', line 1080

def reply_addresses( default = nil )
  reply_to_addrs(nil) or from_addrs(nil) or default
end

#reply_to(default = nil) ⇒ Object

Returns who the email is from as an Array of email address strings instead to an Array of TMail::Address objects which is what Mail#reply_to_addrs returns

Example:

mail = TMail::Mail.new
mail.reply_to = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.reply_to #=>  ["[email protected]", "[email protected]"]



454
455
456
 
# File 'lib/tmail/interface.rb', line 454

def reply_to( default = nil )
  addrs2specs(reply_to_addrs(nil)) || default
end

#reply_to=(*strs) ⇒ Object

Destructively sets the “Reply-To:” field to the passed array of strings (which should be valid email addresses)

Example:

mail = TMail::Mail.new
mail.reply_to = ["[email protected]", "Mikel <[email protected]>"]
mail.reply_to #=>  ["[email protected]", "[email protected]"]
mail['reply_to'].to_s #=> "[email protected], Mikel <[email protected]>"



467
468
469
 
# File 'lib/tmail/interface.rb', line 467

def reply_to=( *strs )
  set_string_array_attr 'Reply-To', strs
end

#reply_to_addrs(default = nil) ⇒ Object

Return a TMail::Addresses instance for each entry in the “Reply-To:” field of the mail object header.

If the “Reply-To:” field does not exist, will return nil by default or the value you pass as the optional parameter.

Example:

mail = TMail::Mail.new
mail.reply_to_addrs #=> nil
mail.reply_to_addrs([]) #=> []
mail.reply_to = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.reply_to_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



424
425
426
427
428
429
430
 
# File 'lib/tmail/interface.rb', line 424

def reply_to_addrs( default = nil )
  if h = @header['reply-to']
    h.addrs.blank? ? default : h.addrs
  else
    default
  end
end

#reply_to_addrs=(arg) ⇒ Object

Destructively set the to value of the “Reply-To:” header to equal the passed in argument.

TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.

Example:

mail = TMail::Mail.new
mail.reply_to_addrs = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.reply_to_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



442
443
444
 
# File 'lib/tmail/interface.rb', line 442

def reply_to_addrs=( arg )
  set_addrfield 'reply-to', arg
end

#send_text_to(smtp) ⇒ Object 



41
42
43
44
45
46
 
# File 'lib/tmail/net.rb', line 41

def send_text_to( smtp )
  do_send_to(smtp) do
    ready_to_send
    mime_encode
  end
end

#send_to(smtp) ⇒ Object 



35
36
37
38
39
 
# File 'lib/tmail/net.rb', line 35

def send_to( smtp )
  do_send_to(smtp) do
    ready_to_send
  end
end

#send_to_0(smtp, from, to) ⇒ Object 



56
57
58
59
60
 
# File 'lib/tmail/net.rb', line 56

def send_to_0( smtp, from, to )
  smtp.ready(from, to) do |f|
    encoded "\r\n", 'j', f, ''
  end
end

#sender(default = nil) ⇒ Object

Returns who the sender of this mail is as string instead to an Array of TMail::Address objects which is what Mail#sender_addr returns

Example:

mail = TMail::Mail.new
mail.sender = "Mikel <[email protected]>"
mail.sender #=>  "[email protected]"



517
518
519
520
521
 
# File 'lib/tmail/interface.rb', line 517

def sender( default = nil )
  f = @header['sender'] or return default
  a = f.addr            or return default
  a.spec
end

#sender=(str) ⇒ Object

Destructively sets the “Sender:” field to the passed string (which should be a valid email address)

Example:

mail = TMail::Mail.new
mail.sender = "[email protected]"
mail.sender #=>  "[email protected]"
mail['sender'].to_s #=> "[email protected]"



532
533
534
 
# File 'lib/tmail/interface.rb', line 532

def sender=( str )
  set_string_attr 'Sender', str
end

#sender_addr(default = nil) ⇒ Object

Return a TMail::Addresses instance of the “Sender:” field of the mail object header.

If the “Sender:” field does not exist, will return nil by default or the value you pass as the optional parameter.

Example:

mail = TMail::Mail.new
mail.sender #=> nil
mail.sender([]) #=> []
mail.sender = "Mikel <[email protected]>"
mail.reply_to_addrs #=>  [#<TMail::Address [email protected]>]



483
484
485
486
 
# File 'lib/tmail/interface.rb', line 483

def sender_addr( default = nil )
  f = @header['sender'] or return default
  f.addr                or return default
end

#sender_addr=(addr) ⇒ Object

Destructively set the to value of the “Sender:” header to equal the passed in argument.

TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.

Example:

mail = TMail::Mail.new
mail.sender_addrs = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.sender_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



498
499
500
501
502
503
504
505
506
507
 
# File 'lib/tmail/interface.rb', line 498

def sender_addr=( addr )
  if addr
    h = HeaderField.internal_new('sender', @config)
    h.addr = addr
    @header['sender'] = h
  else
    @header.delete 'sender'
  end
  addr
end

#set_content_type(str, sub = nil, param = nil) ⇒ Object Also known as: content_type=

Destructively sets the “Content-Type:” header field of this mail object

Allows you to set the main type, sub type as well as parameters to the field. The main type and sub type need to be a string.

The optional params hash can be passed with keys as symbols and values as a string, or strings as keys and values.

Example:

mail = TMail::Mail.new
mail.set_content_type("text", "plain")
mail.to_s #=> "Content-Type: text/plain\n\n"

mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"})
mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n"

mail.set_content_type("text", "plain", {"charset" => "EUC-KR", "format" => "flowed"})
mail.to_s #=> "Content-Type: text/plain; charset=EUC-KR; format=flowed\n\n"



814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
 
# File 'lib/tmail/interface.rb', line 814

def set_content_type( str, sub = nil, param = nil )
  if sub
    main, sub = str, sub
  else
    main, sub = str.split(%r</>, 2)
    raise ArgumentError, "sub type missing: #{str.inspect}" unless sub
  end
  if h = @header['content-type']
    h.main_type = main
    h.sub_type  = sub
    h.params.clear
  else
    store 'Content-Type', "#{main}/#{sub}"
  end
  @header['content-type'].params.replace param if param
  str
end

#set_disposition(str, params = nil) ⇒ Object Also known as: disposition=, set_content_disposition, content_disposition=

Allows you to set the content-disposition of the mail object. Accepts a type and a hash of parameters.

Example:

mail.set_disposition("attachment", {:filename => "test.rb"})
mail.disposition #=> "attachment"
mail['content-disposition'].to_s #=> "attachment; filename=test.rb"



973
974
975
976
977
978
979
980
981
982
 
# File 'lib/tmail/interface.rb', line 973

def set_disposition( str, params = nil )
  if h = @header['content-disposition']
    h.disposition = str
    h.params.clear
  else
    store('Content-Disposition', str)
    h = @header['content-disposition']
  end
  h.params.replace params if params
end

#strftime(fmt, default = nil) ⇒ Object

Returns the time of the mail message formatted to your taste using a strftime format string. If no date set returns nil by default or whatever value you pass as the second optional parameter.

time = Time.now # (on Nov 16 2007)
mail.date = time
mail.strftime("%D") #=> "11/16/07"



148
149
150
151
152
153
154
 
# File 'lib/tmail/interface.rb', line 148

def strftime( fmt, default = nil )
  if t = date
    t.strftime(fmt)
  else
    default
  end
end

#sub_header(key, param) ⇒ Object 



251
252
253
 
# File 'lib/tmail/mail.rb', line 251

def sub_header(key, param)
  (hdr = self[key]) ? hdr[param] : nil
end

#sub_type(default = nil) ⇒ Object

Returns the current sub type of the “Content-Type” of the mail instance.

If the content_type field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.

Example:

mail = TMail::Mail.new
mail.sub_type #=> nil
mail.sub_type([]) #=> []
mail = TMail::Mail.load("../test/fixtures/raw_email")
mail.sub_type #=> "plain"



787
788
789
790
791
792
793
 
# File 'lib/tmail/interface.rb', line 787

def sub_type( default = nil )
  if h = @header['content-type']
    h.sub_type || default
  else
    default
  end
end

#subject(default = nil) ⇒ Object Also known as: quoted_subject

Returns the subject of the mail instance.

If the subject field does not exist, returns nil by default or you can pass in as the parameter for what you want the default value to be.

Example:

mail = TMail::Mail.new
mail.subject #=> nil
mail.subject("") #=> ""
mail.subject = "Hello"
mail.subject #=> "Hello"



550
551
552
 
# File 'lib/tmail/interface.rb', line 550

def subject(to_charset = 'utf-8')
  Unquoter.unquote_and_convert_to(quoted_subject, to_charset)
end

#subject=(str) ⇒ Object

Destructively sets the passed string as the subject of the mail message.

Example

mail = TMail::Mail.new
mail.subject #=> "This subject"
mail.subject = "Another subject"
mail.subject #=> "Another subject"



567
568
569
 
# File 'lib/tmail/interface.rb', line 567

def subject=( str )
  set_string_attr 'Subject', str
end

#text_content_type? ⇒ Boolean

Returns true if this part’s content main type is text, else returns false. By main type is meant “text/plain” is text. “text/html” is text

Returns:

  • (Boolean) 


23
24
25
 
# File 'lib/tmail/attachments.rb', line 23

def text_content_type?
  self.header['content-type'] && (self.header['content-type'].main_type == 'text')
end

#to(default = nil) ⇒ Object

Returns who the email is to as an Array of email addresses as opposed to an Array of TMail::Address objects which is what Mail#to_addrs returns

Example:

mail = TMail::Mail.new
mail.to = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.to #=>  ["[email protected]", "[email protected]"]



268
269
270
 
# File 'lib/tmail/interface.rb', line 268

def to( default = nil )
  addrs2specs(to_addrs(nil)) || default
end

#to=(*strs) ⇒ Object

Destructively sets the “To:” field to the passed array of strings (which should be valid email addresses)

Example:

mail = TMail::Mail.new
mail.to = ["[email protected]", "Mikel <[email protected]>"]
mail.to #=>  ["[email protected]", "[email protected]"]
mail['to'].to_s #=> "[email protected], Mikel <[email protected]>"



305
306
307
 
# File 'lib/tmail/interface.rb', line 305

def to=( *strs )
  set_string_array_attr 'To', strs
end

#to_addrs(default = nil) ⇒ Object

Return a TMail::Addresses instance for each entry in the “To:” field of the mail object header.

If the “To:” field does not exist, will return nil by default or the value you pass as the optional parameter.

Example:

mail = TMail::Mail.new
mail.to_addrs #=> nil
mail.to_addrs([]) #=> []
mail.to = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.to_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



170
171
172
173
174
175
176
 
# File 'lib/tmail/interface.rb', line 170

def to_addrs( default = nil )
  if h = @header['to']
    h.addrs
  else
    default
  end
end

#to_addrs=(arg) ⇒ Object

Destructively set the to field of the “To:” header to equal the passed in string.

TMail will parse your contents and turn each valid email address into a TMail::Address object before assigning it to the mail message.

Example:

mail = TMail::Mail.new
mail.to = "Mikel <[email protected]>, another Mikel <[email protected]>"
mail.to_addrs #=>  [#<TMail::Address [email protected]>, #<TMail::Address [email protected]>]



228
229
230
 
# File 'lib/tmail/interface.rb', line 228

def to_addrs=( arg )
  set_addrfield 'to', arg
end

#transfer_encoding(default = nil) ⇒ Object Also known as: encoding, content_transfer_encoding

Returns the transfer encoding of the email. Returns nil if no encoding set or returns whatever default you pass as a parameter - note passing the parameter does NOT change the mail object in any way.

Example:

mail = TMail::Mail.load("path_to/base64_encoded_email")
mail.transfer_encoding #=> "base64"

mail = TMail::Mail.new
mail.transfer_encoding #=> nil
mail.transfer_encoding("base64") #=> "base64"



916
917
918
919
920
921
922
 
# File 'lib/tmail/interface.rb', line 916

def transfer_encoding( default = nil )
  if h = @header['content-transfer-encoding']
    h.encoding || default
  else
    default
  end
end

#transfer_encoding=(str) ⇒ Object Also known as: encoding=, content_transfer_encoding=

Destructively sets the transfer encoding of the mail object to the passed string, you should note though that this does nothing to the mail body, just changes the header value, you will need to encode or decode the body as well to match whatever you put in this header value.

Example:

mail = TMail::Mail.new
mail.transfer_encoding #=> nil
mail.transfer_encoding = "base64"
mail.transfer_encoding #=> "base64"



935
936
937
 
# File 'lib/tmail/interface.rb', line 935

def transfer_encoding=( str )
  set_string_attr 'Content-Transfer-Encoding', str
end

#type_param(name, default = nil) ⇒ Object

Returns the named type parameter as a string, from the “Content-Type:” header.

Example:

mail = TMail::Mail.new
mail.type_param("charset") #=> nil
mail.type_param("charset", []) #=> []
mail.set_content_type("text", "plain", {:charset => "EUC-KR", :format => "flowed"})
mail.type_param("charset") #=> "EUC-KR"
mail.type_param("format") #=> "flowed"



844
845
846
847
848
849
850
 
# File 'lib/tmail/interface.rb', line 844

def type_param( name, default = nil )
  if h = @header['content-type']
    h[name] || default
  else
    default
  end
end

#unquoted_body(to_charset = 'utf-8') ⇒ Object 



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/tmail/quoting.rb', line 12

def unquoted_body(to_charset = 'utf-8')
  from_charset = charset
  case (content_transfer_encoding || "7bit").downcase
    when "quoted-printable"
      # the default charset is set to iso-8859-1 instead of 'us-ascii'.
      # This is needed as many mailer do not set the charset but send in ISO. This is only used if no charset is set.
      if !from_charset.blank? && from_charset.downcase == 'us-ascii'
        from_charset = 'iso-8859-1'
      end

      Unquoter.unquote_quoted_printable_and_convert_to(quoted_body,
        to_charset, from_charset, true)
    when "base64"
      Unquoter.unquote_base64_and_convert_to(quoted_body, to_charset,
        from_charset)
    when "7bit", "8bit"
      Unquoter.convert_to(quoted_body, to_charset, from_charset)
    when "binary"
      quoted_body
    else
      quoted_body
  end
end

#value?(val) ⇒ Boolean Also known as: has_value?

Returns:

  • (Boolean) 


47
48
49
50
51
 
# File 'lib/tmail/obsolete.rb', line 47

def value?( val )
  HeaderField === val or return false

  [ @header[val.name.downcase] ].flatten.include? val
end

#values ⇒ Object 



41
42
43
44
45
 
# File 'lib/tmail/obsolete.rb', line 41

def values
  ret = []
  each_field {|v| ret.push v }
  ret
end

#values_at(*args) ⇒ Object Also known as: indexes, indices 



379
380
381
 
# File 'lib/tmail/mail.rb', line 379

def values_at( *args )
  args.map {|k| @header[k.downcase] }.flatten
end

#write_back(eol = "\n", charset = 'e') ⇒ Object 



164
165
166
167
 
# File 'lib/tmail/mail.rb', line 164

def write_back( eol = "\n", charset = 'e' )
  parse_body
  @port.wopen {|stream| encoded eol, charset, stream }
end