Class: TMail::Mail

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

Overview

Mail Class

Accessing a TMail object done via the TMail::Mail class. As email can be fairly complex creatures, you will find a large amount of accessor and setter methods in this class!

Most of the below methods handle the header, in fact, what TMail does best is handle the header of the email object. There are only a few methods that deal directly with the body of the email, such as base64_encode and base64_decode.

Using TMail inside your code

The usual way is to install the gem (see the README on how to do this) and then put at the top of your class:

require 'tmail'

You can then create a new TMail object in your code with:

@email = TMail::Mail.new

Or if you have an email as a string, you can initialize a new TMail::Mail object and get it to parse that string for you like so:

@email = TMail::Mail.parse(email_text)

You can also read a single email off the disk, for example:

@email = TMail::Mail.load('filename.txt')

Also, you can read a mailbox (usual unix mbox format) and end up with an array of TMail objects by doing something like this:

# Note, we pass true as the last variable to open the mailbox read only
mailbox = TMail::UNIXMbox.new("mailbox", nil, true)
@emails = []
mailbox.each_port { |m| @emails << TMail::Mail.new(m) }

Constant Summary

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

- (Mail) initialize(port = nil, conf = DEFAULT_CONFIG)

:nodoc:



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) port (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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 150

def port
  @port
end

Class Method Details

+ (Object) boundary



123
124
125
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 123

def Mail.boundary
  ::TMail.new_boundary
end

+ (Object) load(fname) 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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 98

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

+ (Object) msgid



127
128
129
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 127

def Mail.msgid
  ::TMail.new_message_id
end

+ (Object) parse(str)

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

Example:

require 'rubygems'; require 'tmail'
email_string =<<HEREDOC
To: mikel@lindsaar.net
From: mikel@me.com
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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 122

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

Instance Method Details

- (Object) [](key) Also known as: fetch

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

@mail['from']  #=> #<TMail::AddressHeader "mikel@test.com.au">
@mail['to']    #=> #<TMail::AddressHeader "mikel@test.com.au">

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

@mail['to'].to_s #=> "mikel@test.com.au"


247
248
249
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 247

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

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

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

@mail = TMail::Mail.new
@mail['to'].to_s       # => 'mikel@test.com.au'
@mail['to'] = 'mikel@elsewhere.org'
@mail['to'].to_s       # => 'mikel@elsewhere.org'
@mail.encoded          # => "To: mikel@elsewhere.org\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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) accept(strategy)



169
170
171
172
173
174
175
176
177
178
179
180
181
182
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) add_date



86
87
88
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/net.rb', line 86

def add_date
  self.date = Time.now
end

- (Object) add_message_id(fqdn = nil)



80
81
82
83
84
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Boolean) attachment?(part)



31
32
33
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/attachments.rb', line 31

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

- (Object) attachments



35
36
37
38
39
40
41
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/attachments.rb', line 35

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

- (Object) base64_decode

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



1030
1031
1032
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 1030

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

- (Object) base64_decode!

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



1021
1022
1023
1024
1025
1026
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) base64_encode

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



1015
1016
1017
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 1015

def base64_encode
  Base64.folding_encode(self.body)
end

- (Object) base64_encode!

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



1008
1009
1010
1011
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 1008

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

- (Object) bcc(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.bcc #=>  ["mikel@me.org", "mikel@you.org"]


292
293
294
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 292

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

- (Object) bcc=(*strs)

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

Example:

mail = TMail::Mail.new
mail.bcc = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
mail.bcc #=>  ["mikel@abc.org", "mikel@xyz.org"]
mail['bcc'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"


331
332
333
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 331

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

- (Object) bcc_addrs(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.bcc_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


210
211
212
213
214
215
216
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 210

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

- (Object) bcc_addrs=(arg)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.bcc_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


256
257
258
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 256

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

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



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) body=(str)



463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) body_port



445
446
447
448
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 445

def body_port
  parse_body
  @body_port
end

- (Object) cc(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.cc #=>  ["mikel@me.org", "mikel@you.org"]


280
281
282
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 280

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

- (Object) cc=(*strs)

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

Example:

mail = TMail::Mail.new
mail.cc = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
mail.cc #=>  ["mikel@abc.org", "mikel@xyz.org"]
mail['cc'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"


318
319
320
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 318

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

- (Object) cc_addrs(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.cc_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


190
191
192
193
194
195
196
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 190

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

- (Object) cc_addrs=(arg)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.cc_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


242
243
244
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 242

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

- (Object) charset(default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) charset=(str)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) clear



352
353
354
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 352

def clear
  @header.clear
end

- (Object) content_type(default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 747

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

- (Boolean) content_type_is_text?

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



513
514
515
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 513

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

- (Object) create_forward

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 1122

def create_forward
  setup_forward create_empty_mail()
end

- (Object) create_reply

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  #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"]
reply_email.in_reply_to #=> ["<d3b8cf8e49f04480850c28713a1f473e@lindsaar.net>"]


1108
1109
1110
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 1108

def create_reply
  setup_reply create_empty_mail()
end

- (Object) date(default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 115

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

- (Object) date=(time)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 132

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

- (Object) delete(key)



356
357
358
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 356

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

- (Object) delete_if



360
361
362
363
364
365
366
367
368
369
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) delete_no_send_fields



73
74
75
76
77
78
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) destinations(default = nil)

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

Example:

mail.to = "Mikel <mikel@lindsaar.net>"
mail.cc = "Trans <t@t.com>"
mail.bcc = "bob <bob@me.com>"
mail.destinations #=> ["mikel@lindsaar.net", "t@t.com", "bob@me.com"]


1042
1043
1044
1045
1046
1047
1048
1049
1050
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) disposition(default = nil) 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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 955

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

- (Boolean) disposition_is_attachment?

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



507
508
509
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 507

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

- (Object) disposition_param(name, default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 998

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

- (Object) each(&block)



450
451
452
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 450

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

- (Object) each_destination(&block) 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: mikel@lindsaar.net
String: t@t.com
String: bob@me.com


1058
1059
1060
1061
1062
1063
1064
1065
1066
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) each_field(&block) Also known as: each_value



323
324
325
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 323

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

- (Object) each_header Also known as: each_pair

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

@mail['to'] = 'mikel@elsewhere.org'
@mail['from'] = 'me@me.com'
@mail.each_header { |k,v| puts "#{k} = #{v}" }
# => from = me@me.com
# => to = mikel@elsewhere.org


309
310
311
312
313
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 309

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

- (Object) each_header_name(&block) Also known as: each_key



317
318
319
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 317

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

- (Object) each_part(&block)



501
502
503
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 501

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

- (Object) enforced_message_id=(str)

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 = "<348F04F142D69C21-291E56D292BC@xxxx.net>"
mail.message_id #=> "<348F04F142D69C21-291E56D292BC@xxxx.net>"
mail.ready_to_send
mail.message_id #=> "<348F04F142D69C21-291E56D292BC@xxxx.net>"


626
627
628
629
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 626

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

- (Object) epilogue



485
486
487
488
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 485

def epilogue
  parse_body
  @epilogue.dup
end

- (Object) epilogue=(str)



490
491
492
493
494
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 490

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

- (Object) error_reply_addresses(default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 1086

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

- (Object) friendly_from(default = nil)

Returns the “friendly” human readable part of the address

Example:

mail = TMail::Mail.new
mail.from = "Mikel Lindsaar <mikel@abc.com>"
mail.friendly_from #=> "Mikel Lindsaar"


403
404
405
406
407
408
409
410
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) from(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.from #=>  ["mikel@me.org", "mikel@you.org"]


379
380
381
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 379

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

- (Object) from=(*strs)

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

Example:

mail = TMail::Mail.new
mail.from = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
mail.from #=>  ["mikel@abc.org", "mikel@xyz.org"]
mail['from'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"


392
393
394
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 392

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

- (Object) from_addr(default = nil)



57
58
59
60
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 57

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

- (Object) from_address(default = nil)



62
63
64
65
66
67
68
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 62

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

- (Object) from_address=



70
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 70

alias from_address= from_addrs=

- (Object) from_addrs(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.from_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


349
350
351
352
353
354
355
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 349

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

- (Object) from_addrs=(arg)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.from_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


367
368
369
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 367

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

- (Object) from_phrase(default = nil)



72
73
74
75
76
77
78
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 72

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

- (Boolean) has_attachments?



17
18
19
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/attachments.rb', line 17

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

- (Object) header



235
236
237
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 235

def header
  @header.dup
end

- (Object) header_string(name, default = nil)

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 <mikel@lindsaar.net>"
mail.header_string("From") #=> "mikel <mikel@lindsaar.net>"


49
50
51
52
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 49

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

- (Object) in_reply_to(default = nil)

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 #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]


643
644
645
646
647
648
649
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 643

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

- (Object) in_reply_to=(*idstrs)

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 = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
mail.in_reply_to #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]


660
661
662
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 660

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

- (Boolean) inline_attachment?(part)



27
28
29
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) inspect



152
153
154
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 152

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

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



375
376
377
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 375

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

- (Object) keys



371
372
373
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 371

def keys
  @header.keys
end

- (Object) main_type(default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 767

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

- (Object) message_id(default = nil)

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) #=> "<47404c5326d9c_2ad4fbb80161@baci.local.tmail>"
mail.message_id = TMail.new_message_id
mail.message_id #=> "<47404c5326d9c_2ad4fbb80161@baci.local.tmail>"


585
586
587
588
589
590
591
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 585

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

- (Object) message_id=(str)

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 = "<348F04F142D69C21-291E56D292BC@xxxx.net>"
mail.message_id #=> "<348F04F142D69C21-291E56D292BC@xxxx.net>"
mail.message_id = "this_is_my_badly_formatted_message_id"
mail.message_id #=> nil


611
612
613
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 611

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

- (Object) mime_encode



90
91
92
93
94
95
96
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/net.rb', line 90

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

- (Object) mime_encode_binary(body)



114
115
116
117
118
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) mime_encode_multipart(top = true)



120
121
122
123
124
125
126
127
128
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) mime_encode_singlepart



98
99
100
101
102
103
104
105
106
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) mime_encode_text(body)



108
109
110
111
112
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) mime_version(default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 713

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

- (Object) mime_version=(m, opt = nil)



721
722
723
724
725
726
727
728
729
730
731
732
733
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) mime_version_charset

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 876

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

- (Object) msgid



80
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 80

alias msgid  message_id

- (Object) msgid=



81
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 81

alias msgid= message_id=

- (Boolean) multipart?

Returns true if the Mail object is a multipart message



1095
1096
1097
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 1095

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

- (Object) ordered_each



340
341
342
343
344
345
346
347
348
349
350
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) parts



496
497
498
499
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 496

def parts
  parse_body
  @parts
end

- (Object) quoted_body Also known as: preamble



454
455
456
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 454

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

- (Object) quoted_body=(str) Also known as: preamble=



458
459
460
461
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 458

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

- (Object) ready_to_send



62
63
64
65
66
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/net.rb', line 62

def ready_to_send
  delete_no_send_fields
  add_message_id
  add_date
end

- (Object) references(default = nil)

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 #=> ["<473FF3B8.9020707@xxx.org>", "<348F04F142D69C21-291E56D292BC@xxxx.net>"]


678
679
680
681
682
683
684
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 678

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

- (Object) references=(*strs)

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 = ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]
mail.references #=> ["<348F04F142D69C21-291E56D292BC@xxxx.net>"]


695
696
697
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 695

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

- (Object) reply_addresses(default = nil)

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 <mikel@lindsaar.net>"
mail.reply_to = nil
mail.reply_addresses #=> [""]


1080
1081
1082
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 1080

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

- (Object) reply_to(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.reply_to #=>  ["mikel@me.org", "mikel@you.org"]


454
455
456
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 454

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

- (Object) reply_to=(*strs)

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 = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
mail.reply_to #=>  ["mikel@abc.org", "mikel@xyz.org"]
mail['reply_to'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"


467
468
469
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 467

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

- (Object) reply_to_addrs(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.reply_to_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


424
425
426
427
428
429
430
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) reply_to_addrs=(arg)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.reply_to_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


442
443
444
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 442

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

- (Object) send_text_to(smtp)



41
42
43
44
45
46
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/net.rb', line 41

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

- (Object) send_to(smtp)



35
36
37
38
39
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/net.rb', line 35

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

- (Object) send_to_0(smtp, from, to)



56
57
58
59
60
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) sender(default = nil)

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 <mikel@me.org>"
mail.sender #=>  "mikel@me.org"


517
518
519
520
521
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 517

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

- (Object) sender=(str)

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

Example:

mail = TMail::Mail.new
mail.sender = "mikel@abc.com"
mail.sender #=>  "mikel@abc.org"
mail['sender'].to_s #=> "mikel@abc.com"


532
533
534
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 532

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

- (Object) sender_addr(default = nil)

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 <mikel@me.org>"
mail.reply_to_addrs #=>  [#<TMail::Address mikel@me.org>]


483
484
485
486
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 483

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

- (Object) sender_addr=(addr)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.sender_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


498
499
500
501
502
503
504
505
506
507
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) set_content_type(str, sub = nil, param = nil) 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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) set_disposition(str, params = nil) 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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Object) strftime(fmt, default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 148

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

- (Object) sub_header(key, param)



251
252
253
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 251

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

- (Object) sub_type(default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 787

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

- (Object) subject(default = nil) 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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 550

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

- (Object) subject=(str)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 567

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

- (Boolean) text_content_type?

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



23
24
25
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/attachments.rb', line 23

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

- (Object) to(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.to #=>  ["mikel@me.org", "mikel@you.org"]


268
269
270
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 268

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

- (Object) to=(*strs)

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

Example:

mail = TMail::Mail.new
mail.to = ["mikel@abc.com", "Mikel <mikel@xyz.com>"]
mail.to #=>  ["mikel@abc.org", "mikel@xyz.org"]
mail['to'].to_s #=> "mikel@abc.com, Mikel <mikel@xyz.com>"


305
306
307
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 305

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

- (Object) to_addrs(default = nil)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.to_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


170
171
172
173
174
175
176
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 170

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

- (Object) to_addrs=(arg)

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 <mikel@me.org>, another Mikel <mikel@you.org>"
mail.to_addrs #=>  [#<TMail::Address mikel@me.org>, #<TMail::Address mikel@you.org>]


228
229
230
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 228

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

- (Object) transfer_encoding(default = nil) 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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 916

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

- (Object) transfer_encoding=(str) 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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 935

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

- (Object) type_param(name, default = nil)

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 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/interface.rb', line 844

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

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



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/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

- (Boolean) value?(val) Also known as: has_value?



47
48
49
50
51
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 47

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

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

- (Object) values



41
42
43
44
45
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/obsolete.rb', line 41

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

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



379
380
381
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 379

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

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



164
165
166
167
# File 'actionmailer/lib/action_mailer/vendor/tmail-1.2.7/tmail/mail.rb', line 164

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