Class: TMail::Mail

Inherits:
Object show all
Includes:
StrategyInterface, TextUtils
Defined in:
lib/gems/tmail-1.2.3.1/lib/tmail/mail.rb,
lib/gems/tmail-1.2.3.1/lib/tmail/net.rb,
lib/gems/tmail-1.2.3.1/lib/tmail/quoting.rb,
lib/gems/tmail-1.2.3.1/lib/tmail/obsolete.rb,
lib/gems/tmail-1.2.3.1/lib/tmail/obsolete.rb,
lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb,
lib/gems/tmail-1.2.3.1/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, #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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/lib/tmail/mail.rb', line 150

def port
  @port
end

Class Method Details

.boundary ⇒ Object 



123
124
125
 
# File 'lib/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/lib/tmail/mail.rb', line 98

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

.msgid ⇒ Object 



127
128
129
 
# File 'lib/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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. Eamples:

@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 actualy 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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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 



84
85
86
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/net.rb', line 84

def add_date
  self.date = Time.now
end

#add_message_id(fqdn = nil) ⇒ Object 



80
81
82
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/net.rb', line 80

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

#attachment?(part) ⇒ Boolean

Returns:

  • (Boolean) 


19
20
21
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/attachments.rb', line 19

def attachment?(part)
  part.disposition_is_attachment? || part.content_type_is_text?
end

#attachments ⇒ Object 



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/attachments.rb', line 23

def attachments
  if multipart?
    parts.collect { |part| 
      if part.multipart?
        part.attachments
      elsif attachment?(part)
        content   = part.body # unquoted automatically by TMail#body
        file_name = (part['content-location'] &&
                      part['content-location'].body) ||
                    part.sub_header("content-type", "name") ||
                    part.sub_header("content-disposition", "filename")
        
        next if file_name.blank? || content.blank?
        
        attachment = Attachment.new(content)
        attachment.original_filename = file_name.strip
        attachment.content_type = part.content_type
        attachment
      end
    }.flatten.compact
  end      
end

#base64_decode ⇒ Object

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



993
994
995
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 993

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



984
985
986
987
988
989
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 984

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



978
979
980
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 978

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



971
972
973
974
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 971

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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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"



837
838
839
840
841
842
843
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 837

def charset( default = nil )
  if h = @header['content-type']
    h['charset'] or default
  else
    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"



856
857
858
859
860
861
862
863
864
865
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 856

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/gems/tmail-1.2.3.1/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"



720
721
722
723
724
725
726
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 720

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/gems/tmail-1.2.3.1/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



1085
1086
1087
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 1085

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]>"]



1071
1072
1073
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 1071

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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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]"]



1005
1006
1007
1008
1009
1010
1011
1012
1013
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 1005

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



918
919
920
921
922
923
924
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 918

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/gems/tmail-1.2.3.1/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"



961
962
963
964
965
966
967
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 961

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/gems/tmail-1.2.3.1/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]



1021
1022
1023
1024
1025
1026
1027
1028
1029
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 1021

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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/lib/tmail/mail.rb', line 501

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

#epilogue ⇒ Object 



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

def epilogue
  parse_body
  @epilogue.dup
end

#epilogue=(str) ⇒ Object 



490
491
492
493
494
 
# File 'lib/gems/tmail-1.2.3.1/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.



1049
1050
1051
1052
1053
1054
1055
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 1049

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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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) 


15
16
17
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/attachments.rb', line 15

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

#header ⇒ Object 



235
236
237
 
# File 'lib/gems/tmail-1.2.3.1/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 contnts of the field

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



49
50
51
52
 
# File 'lib/gems/tmail-1.2.3.1/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]>"]



616
617
618
619
620
621
622
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 616

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]>"]



633
634
635
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 633

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

#inspect ⇒ Object 



152
153
154
 
# File 'lib/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/lib/tmail/mail.rb', line 375

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

#keys ⇒ Object 



371
372
373
 
# File 'lib/gems/tmail-1.2.3.1/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"



740
741
742
743
744
745
746
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 740

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/gems/tmail-1.2.3.1/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

Example:

mail = TMail::Mail.new
mail.message_id = "this_is_my_badly_formatted_message_id"
mail.message_id #=> "this_is_my_badly_formatted_message_id"



600
601
602
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 600

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

#mime_encode ⇒ Object 



88
89
90
91
92
93
94
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/net.rb', line 88

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

#mime_encode_binary(body) ⇒ Object 



112
113
114
115
116
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/net.rb', line 112

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 



118
119
120
121
122
123
124
125
126
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/net.rb', line 118

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 



96
97
98
99
100
101
102
103
104
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/net.rb', line 96

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 



106
107
108
109
110
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/net.rb', line 106

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"



686
687
688
689
690
691
692
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 686

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

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



694
695
696
697
698
699
700
701
702
703
704
705
706
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 694

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

#msgid ⇒ Object 



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

alias msgid  message_id

#msgid= ⇒ Object 



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

alias msgid= message_id=

#multipart? ⇒ Boolean

Returns true if the Mail object is a multipart message

Returns:

  • (Boolean) 


1058
1059
1060
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 1058

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

#ordered_each ⇒ Object 



340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/lib/tmail/mail.rb', line 496

def parts
  parse_body
  @parts
end

#quoted_body ⇒ Object Also known as: preamble 



454
455
456
 
# File 'lib/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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]>"]



651
652
653
654
655
656
657
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 651

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]>"]



668
669
670
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 668

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 #=> [""]



1043
1044
1045
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 1043

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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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"



787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 787

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"



936
937
938
939
940
941
942
943
944
945
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 936

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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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"



760
761
762
763
764
765
766
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 760

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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 567

def subject=( str )
  set_string_attr 'Subject', str
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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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"



879
880
881
882
883
884
885
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 879

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"



898
899
900
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 898

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"



817
818
819
820
821
822
823
 
# File 'lib/gems/tmail-1.2.3.1/lib/tmail/interface.rb', line 817

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/gems/tmail-1.2.3.1/lib/tmail/quoting.rb', line 12

def unquoted_body(to_charset = 'utf-8')
  from_charset = sub_header("content-type", "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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/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/gems/tmail-1.2.3.1/lib/tmail/mail.rb', line 164

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