Class: TMail::Mail

### Home Classes Methods

### In Files

- lib/tmail/attachments.rb
- lib/tmail/interface.rb
- lib/tmail/mail.rb
- lib/tmail/net.rb

### Parent

Object

### Methods

- ::load
- ::load_from
- ::loadfrom
- ::parse
- #[]
- #[]=
- #accept
- #add_date
- #add_message_id
- #attachment?
- #attachments
- #base64_decode
- #base64_decode!
- #base64_encode
- #base64_encode!
- #bcc
- #bcc=
- #bcc_addrs
- #bcc_addrs=
- #body=
- #body_port
- #cc
- #cc=
- #cc_addrs
- #cc_addrs=
- #charset
- #charset=
- #clear
- #content_disposition
- #content_disposition=
- #content_transfer_encoding
- #content_transfer_encoding=
- #content_type
- #content_type=
- #content_type_is_text?
- #create_forward
- #create_reply
- #date
- #date=
- #delete
- #delete_if
- #delete_no_send_fields
- #destinations
- #disposition
- #disposition=
- #disposition_is_attachment?
- #disposition_param
- #each
- #each_dest
- #each_destination
- #each_field
- #each_header
- #each_header_name
- #each_key
- #each_pair
- #each_part
- #each_value
- #encoding
- #encoding=
- #enforced_message_id=
- #epilogue
- #epilogue=
- #error_reply_addresses
- #fetch
- #friendly_from
- #from
- #from=
- #from_addrs
- #from_addrs=
- #has_attachments?
- #header
- #header_string
- #in_reply_to
- #in_reply_to=
- #indexes
- #indices
- #inline_attachment?
- #inspect
- #key?
- #keys
- #main_type
- #message_id
- #message_id=
- #mime_encode
- #mime_encode_binary
- #mime_encode_multipart
- #mime_encode_singlepart
- #mime_encode_text
- #mime_version
- #mime_version=
- #mime_version_charset
- #multipart?
- #ordered_each
- #parts
- #preamble
- #preamble=
- #quoted_body
- #quoted_body=
- #quoted_subject
- #ready_to_send
- #references
- #references=
- #reply_addresses
- #reply_to
- #reply_to=
- #reply_to_addrs
- #reply_to_addrs=
- #send_text_to
- #send_to
- #send_to_0
- #sender
- #sender=
- #sender_addr
- #sender_addr=
- #set_content_disposition
- #set_content_type
- #set_disposition
- #store
- #strftime
- #sub_header
- #sub_type
- #subject
- #subject=
- #text_content_type?
- #to
- #to=
- #to_addrs
- #to_addrs=
- #transfer_encoding
- #transfer_encoding=
- #type_param
- #values_at
- #write_back

### Included Modules

- StrategyInterface

### Files

- CHANGES
- LICENSE
- NOTES
- README
- Rakefile
- MANIFEST
- Makefile
- depend
- Makefile
- COPYING
- README

### Class/Module Index

Quicksearch

- TMail
- TMail::Address
- TMail::AddressGroup
- TMail::AddressHeader
- TMail::Attachment
- TMail::ContentDispositionHeader
- TMail::ContentTransferEncodingHeader
- TMail::ContentTypeHeader
- TMail::DateTimeHeader
- TMail::EncryptedHeader
- TMail::FilePort
- TMail::HeaderField
- TMail::KeywordsHeader
- TMail::Mail
- TMail::MailFlags
- TMail::Maildir
- TMail::MaildirLoader
- TMail::MaildirPort
- TMail::MboxLoader
- TMail::MessageIdHeader
- TMail::MhLoader
- TMail::MhMailbox
- TMail::MhPort
- TMail::MimeVersionHeader
- TMail::Parser
- TMail::Port
- TMail::ReceivedHeader
- TMail::ReferencesHeader
- TMail::ReturnPathHeader
- TMail::SingleAddressHeader
- TMail::StringPort
- TMail::StructuredHeader
- TMail::SyntaxError
- TMail::TMailScanner
- TMail::TextUtils
- TMail::UNIXMbox
- TMail::UnstructuredHeader
- CharDet
- CharDet::Big5DistributionAnalysis
- CharDet::Big5Prober
- CharDet::CharDistributionAnalysis
- CharDet::CharSetGroupProber
- CharDet::CharSetProber
- CharDet::CodingStateMachine
- CharDet::EUCJPContextAnalysis
- CharDet::EUCJPDistributionAnalysis
- CharDet::EUCJPProber
- CharDet::EUCKRDistributionAnalysis
- CharDet::EUCKRProber
- CharDet::EUCTWDistributionAnalysis
- CharDet::EUCTWProber
- CharDet::EscCharSetProber
- CharDet::GB2312DistributionAnalysis
- CharDet::GB2312Prober
- CharDet::HebrewProber
- CharDet::JapaneseContextAnalysis
- CharDet::Latin1Prober
- CharDet::MBCSGroupProber
- CharDet::MultiByteCharSetProber
- CharDet::SBCSGroupProber
- CharDet::SJISContextAnalysis
- CharDet::SJISDistributionAnalysis
- CharDet::SJISProber
- CharDet::SingleByteCharSetProber
- CharDet::UTF8Prober
- CharDet::UniversalDetector

No matching classes.

# TMail::Mail

## 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) }

### Constants

ALLOW_MULTIPLE

  header

FIELD_ORDER
NOSEND_FIELDS
USE_ARRAY

### Attributes

port[R]

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>

### Public Class Methods

load( fname ) click to toggle source

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')

    # File lib/tmail/mail.rb, line 98
    def load( fname )
      new(FilePort.new(fname))
    end

Also aliased as: load_from, loadfrom
load_from( fname ) click to toggle source
Alias for: load
loadfrom( fname ) click to toggle source
Alias for: load
parse( str ) click to toggle source

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"

    # File lib/tmail/mail.rb, line 122
    def parse( str )
      new(StringPort.new(str))
    end

### Public Instance Methods

[]( key ) click to toggle source

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"

    # File lib/tmail/mail.rb, line 247
    def []( key )
      @header[key.downcase]
    end

Also aliased as: fetch
[]=( key, val ) click to toggle source

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

    # File lib/tmail/mail.rb, line 270
    def []=( key, val )
      dkey = key.downcase

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

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

      val
    end

Also aliased as: store
accept( strategy ) click to toggle source

    # File lib/tmail/mail.rb, line 169
    def accept( strategy )
      with_multipart_encoding(strategy) {
          ordered_each do |name, field|
            next if field.empty?
            strategy.header_name canonical(name)
            field.accept strategy
            strategy.puts
          end
          strategy.puts
          body_port().ropen {|r|
              strategy.write r.read
          }
      }
    end

add_date() click to toggle source

    # File lib/tmail/net.rb, line 86
    def add_date
      self.date = Time.now
    end

add_message_id( fqdn = nil ) click to toggle source

    # File lib/tmail/net.rb, line 80
    def add_message_id( fqdn = nil )
      unless @message_id_enforced
        self.message_id = ::TMail::new_message_id(fqdn)
      end
    end

attachment?(part) click to toggle source

    # File lib/tmail/attachments.rb, line 31
    def attachment?(part)
      part.disposition_is_attachment? || (!part.content_type.nil? && !part.text_content_type?) unless part.multipart?
    end

attachments() click to toggle source

    # File lib/tmail/attachments.rb, line 35
    def attachments
      if multipart?
        parts.collect { |part| attachment(part) }.flatten.compact
      elsif attachment?(self)
        [attachment(self)]
      end
    end

base64_decode() click to toggle source

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

    # File lib/tmail/interface.rb, line 1030
    def base64_decode
      Base64.decode(self.body, @config.strict_base64decode?)
    end

base64_decode!() click to toggle source

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

    # File lib/tmail/interface.rb, line 1021
    def base64_decode!
      if /base64/ === self.transfer_encoding('')
        store 'Content-Transfer-Encoding', '8bit'
        self.body = base64_decode
      end
    end

base64_encode() click to toggle source

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

    # File lib/tmail/interface.rb, line 1015
    def base64_encode
      Base64.folding_encode(self.body)
    end

base64_encode!() click to toggle source

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

    # File lib/tmail/interface.rb, line 1008
    def base64_encode!
      store 'Content-Transfer-Encoding', 'Base64'
      self.body = base64_encode
    end

bcc( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 292
    def bcc( default = nil )
      addrs2specs(bcc_addrs(nil)) || default
    end

bcc=( *strs ) click to toggle source

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

    # File lib/tmail/interface.rb, line 331
    def bcc=( *strs )
      set_string_array_attr 'Bcc', strs
    end

bcc_addrs( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 210
    def bcc_addrs( default = nil )
      if h = @header['bcc']
        h.addrs
      else
        default
      end
    end

bcc_addrs=( arg ) click to toggle source

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

    # File lib/tmail/interface.rb, line 256
    def bcc_addrs=( arg )
      set_addrfield 'bcc', arg
    end

body=( str ) click to toggle source

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

body_port() click to toggle source

body

    # File lib/tmail/mail.rb, line 445
    def body_port
      parse_body
      @body_port
    end

cc( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 280
    def cc( default = nil )
      addrs2specs(cc_addrs(nil)) || default
    end

cc=( *strs ) click to toggle source

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

    # File lib/tmail/interface.rb, line 318
    def cc=( *strs )
      set_string_array_attr 'Cc', strs
    end

cc_addrs( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 190
     def cc_addrs( default = nil )
      if h = @header['cc']
        h.addrs
      else
        default
      end
    end

cc_addrs=( arg ) click to toggle source

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

    # File lib/tmail/interface.rb, line 242
    def cc_addrs=( arg )
      set_addrfield 'cc', arg
    end

charset( default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 864
    def charset( default = nil )
      if h = @header['content-type']
        h['charset'] or default
      else
        mime_version_charset || default
      end
    end

charset=( str ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 893
    def charset=( str )
      if str
        if h = @header[ 'content-type' ]
          h['charset'] = str
        else
          store 'Content-Type', "text/plain; charset=#{str}"
        end
      end
      str
    end

clear() click to toggle source

    # File lib/tmail/mail.rb, line 352
    def clear
      @header.clear
    end

content_disposition( default = nil ) click to toggle source
Alias for: disposition
content_disposition=( str, params = nil ) click to toggle source
Alias for: set_disposition
content_transfer_encoding( default = nil ) click to toggle source
Alias for: transfer_encoding
content_transfer_encoding=( str ) click to toggle source
Alias for: transfer_encoding=
content_type( default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 747
    def content_type( default = nil )
      if h = @header['content-type']
        h.content_type || default
      else
        default
      end
    end

content_type=( str, sub = nil, param = nil ) click to toggle source
Alias for: set_content_type
content_type_is_text?() click to toggle source

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

    # File lib/tmail/mail.rb, line 513
    def content_type_is_text?
      self.header['content-type'] && (self.header['content-type'].main_type != "text")
    end

create_forward() click to toggle source

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

    # File lib/tmail/interface.rb, line 1122
    def create_forward
      setup_forward create_empty_mail()
    end

create_reply() click to toggle source

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

    # File lib/tmail/interface.rb, line 1108
    def create_reply
      setup_reply create_empty_mail()
    end

date( default = nil ) click to toggle source

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.

    # File lib/tmail/interface.rb, line 115
    def date( default = nil )
      if h = @header['date']
        h.date
      else
        default
      end
    end

date=( time ) click to toggle source

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

    # File lib/tmail/interface.rb, line 132
    def date=( time )
      if time
        store 'Date', time2str(time)
      else
        @header.delete 'date'
      end
      time
    end

delete( key ) click to toggle source

    # File lib/tmail/mail.rb, line 356
    def delete( key )
      @header.delete key.downcase
    end

delete_if() click to toggle source

    # File lib/tmail/mail.rb, line 360
    def delete_if
      @header.delete_if do |key,val|
        if Array === val
          val.delete_if {|v| yield key, v }
          val.empty?
        else
          yield key, val
        end
      end
    end

delete_no_send_fields() click to toggle source

    # File lib/tmail/net.rb, line 73
    def delete_no_send_fields
      NOSEND_FIELDS.each do |nm|
        delete nm
      end
      delete_if {|n,v| v.empty? }
    end

destinations( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 1042
    def destinations( default = nil )
      ret = []
      %( 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 ) click to toggle source

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

    # File lib/tmail/interface.rb, line 955
    def disposition( default = nil )
      if h = @header['content-disposition']
        h.disposition || default
      else
        default
      end
    end

Also aliased as: content_disposition
disposition=( str, params = nil ) click to toggle source
Alias for: set_disposition
disposition_is_attachment?() click to toggle source

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

    # File lib/tmail/mail.rb, line 507
    def disposition_is_attachment?
      (self['content-disposition'] && self['content-disposition'].disposition == "attachment")
    end

disposition_param( name, default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 998
    def disposition_param( name, default = nil )
      if h = @header['content-disposition']
        h[name] || default
      else
        default
      end
    end

each( &block ) click to toggle source

    # File lib/tmail/mail.rb, line 450
    def each( &block )
      body_port().ropen {|f| f.each(&block) }
    end

each_dest( &block ) click to toggle source
Alias for: each_destination
each_destination( &block ) click to toggle source

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

    # File lib/tmail/interface.rb, line 1058
    def each_destination( &block )
      destinations([]).each do |i|
        if Address === i
          yield i
        else
          i.each(&block)
        end
      end
    end

Also aliased as: each_dest
each_field( &block ) click to toggle source

    # File lib/tmail/mail.rb, line 323
    def each_field( &block )
      @header.values.flatten.each(&block)
    end

Also aliased as: each_value
each_header() click to toggle source

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

    # File lib/tmail/mail.rb, line 309
    def each_header
      @header.each do |key, val|
        [val].flatten.each {|v| yield key, v }
      end
    end

Also aliased as: each_pair
each_header_name( &block ) click to toggle source

    # File lib/tmail/mail.rb, line 317
    def each_header_name( &block )
      @header.each_key(&block)
    end

Also aliased as: each_key
each_key( &block ) click to toggle source
Alias for: each_header_name
each_pair() click to toggle source
Alias for: each_header
each_part( &block ) click to toggle source

    # File lib/tmail/mail.rb, line 501
    def each_part( &block )
      parts().each(&block)
    end

each_value( &block ) click to toggle source
Alias for: each_field
encoding( default = nil ) click to toggle source
Alias for: transfer_encoding
encoding=( str ) click to toggle source
Alias for: transfer_encoding=
enforced_message_id=( str ) click to toggle source

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

    # File lib/tmail/interface.rb, line 626
    def enforced_message_id=( str )
      @message_id_enforced = true
      self.message_id = ( str )
    end

epilogue() click to toggle source

    # File lib/tmail/mail.rb, line 485
    def epilogue
      parse_body
      @epilogue.dup
    end

epilogue=( str ) click to toggle source

    # File lib/tmail/mail.rb, line 490
    def epilogue=( str )
      parse_body
      @epilogue = str
      str
    end

error_reply_addresses( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 1086
    def error_reply_addresses( default = nil )
      if s = sender(nil)
        [s]
      else
        from_addrs(default)
      end
    end

fetch( key ) click to toggle source
Alias for: []
friendly_from( default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 403
    def friendly_from( default = nil )
      h = @header['from']
      a, = h.addrs
      return default unless a
      return a.phrase if a.phrase
      return h.comments.join(' ') unless h.comments.empty?
      a.spec
    end

from( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 379
    def from( default = nil )
      addrs2specs(from_addrs(nil)) || default
    end

from=( *strs ) click to toggle source

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

    # File lib/tmail/interface.rb, line 392
    def from=( *strs )
      set_string_array_attr 'From', strs
    end

from_addrs( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 349
    def from_addrs( default = nil )
      if h = @header['from']
        h.addrs
      else
        default
      end
    end

from_addrs=( arg ) click to toggle source

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

    # File lib/tmail/interface.rb, line 367
    def from_addrs=( arg )
      set_addrfield 'from', arg
    end

has_attachments?() click to toggle source

    # File lib/tmail/attachments.rb, line 17
    def has_attachments?
      attachment?(self) || multipart? && parts.any? { |part| attachment?(part) }
    end

header() click to toggle source

    # File lib/tmail/mail.rb, line 235
    def header
      @header.dup
    end

header_string( name, default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 49
    def header_string( name, default = nil )
      h = @header[name.downcase] or return default
      h.to_s
    end

in_reply_to( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 643
    def in_reply_to( default = nil )
      if h = @header['in-reply-to']
        h.ids
      else
        default
      end
    end

in_reply_to=( *idstrs ) click to toggle source

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

    # File lib/tmail/interface.rb, line 660
    def in_reply_to=( *idstrs )
      set_string_array_attr 'In-Reply-To', idstrs
    end

indexes( *args ) click to toggle source
Alias for: values_at
indices( *args ) click to toggle source
Alias for: values_at
inline_attachment?(part) click to toggle source

    # File lib/tmail/attachments.rb, line 27
    def inline_attachment?(part)
      part['content-id'] || (part['content-disposition'] && part['content-disposition'].disposition == 'inline' && !part.text_content_type?)
    end

inspect() click to toggle source

    # File lib/tmail/mail.rb, line 152
    def inspect
      "\#<#{self.class} port=#{@port.inspect} bodyport=#{@body_port.inspect}>"
    end

key?( key ) click to toggle source

    # File lib/tmail/mail.rb, line 375
    def key?( key )
      @header.key? key.downcase
    end

keys() click to toggle source

    # File lib/tmail/mail.rb, line 371
    def keys
      @header.keys
    end

main_type( default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 767
    def main_type( default = nil )
      if h = @header['content-type']
        h.main_type || default
      else
        default
      end
    end

message_id( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 585
    def message_id( default = nil )
      if h = @header['message-id']
        h.id || default
      else
        default
      end
    end

message_id=( str ) click to toggle source

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

    # File lib/tmail/interface.rb, line 611
    def message_id=( str )
      set_string_attr 'Message-Id', str
    end

mime_encode() click to toggle source

    # File lib/tmail/net.rb, line 90
    def mime_encode
      if parts.empty?
        mime_encode_singlepart
      else
        mime_encode_multipart true
      end
    end

mime_encode_binary( body ) click to toggle source

    # File lib/tmail/net.rb, line 114
    def mime_encode_binary( body )
      self.body = [body].pack('m')
      self.set_content_type 'application', 'octet-stream'
      self.encoding = 'Base64'
    end

mime_encode_multipart( top = true ) click to toggle source

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

mime_encode_singlepart() click to toggle source

    # File lib/tmail/net.rb, line 98
    def mime_encode_singlepart
      self.mime_version = '1.0'
      b = body
      if NKF.guess(b) != NKF::BINARY
        mime_encode_text b
      else
        mime_encode_binary b
      end
    end

mime_encode_text( body ) click to toggle source

    # File lib/tmail/net.rb, line 108
    def mime_encode_text( body )
      self.body = NKF.nkf('-j -m0', body)
      self.set_content_type 'text', 'plain', {'charset' => 'iso-2022-jp'}
      self.encoding = '7bit'
    end

mime_version( default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 713
    def mime_version( default = nil )
      if h = @header['mime-version']
        h.version || default
      else
        default
      end
    end

mime_version=( m, opt = nil ) click to toggle source

    # File lib/tmail/interface.rb, line 721
    def mime_version=( m, opt = nil )
      if opt
        if h = @header['mime-version']
          h.major = m
          h.minor = opt
        else
          store 'Mime-Version', "#{m}.#{opt}"
        end
      else
        store 'Mime-Version', m
      end
      m
    end

mime_version_charset() click to toggle source

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

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

    # File lib/tmail/interface.rb, line 876
    def mime_version_charset
      if header['mime-version'].inspect =~ /charset=('|\\")?([^\\"']+)/
        $2
      end
    end

multipart?() click to toggle source

Returns true if the Mail object is a multipart message

    # File lib/tmail/interface.rb, line 1095
    def multipart?
      main_type('').downcase == 'multipart'
    end

ordered_each() click to toggle source

    # File lib/tmail/mail.rb, line 340
    def ordered_each
      list = @header.keys
      FIELD_ORDER.each do |name|
        if list.delete(name)
          [@header[name]].flatten.each {|v| yield name, v }
        end
      end
      list.each do |name|
        [@header[name]].flatten.each {|v| yield name, v }
      end
    end

parts() click to toggle source

    # File lib/tmail/mail.rb, line 496
    def parts
      parse_body
      @parts
    end

preamble() click to toggle source
Alias for: quoted_body
preamble=(str) click to toggle source
Alias for: quoted_body=
quoted_body() click to toggle source

    # File lib/tmail/mail.rb, line 454
    def quoted_body
      body_port.ropen {|f| return f.read }
    end

Also aliased as: preamble
quoted_body=(str) click to toggle source

    # File lib/tmail/mail.rb, line 458
    def quoted_body= str
      body_port.wopen { |f| f.write str }
      str
    end

Also aliased as: preamble=
quoted_subject( default = nil ) click to toggle source
Alias for: subject
ready_to_send() click to toggle source

    # File lib/tmail/net.rb, line 62
    def ready_to_send
      delete_no_send_fields
      add_message_id
      add_date
    end

references( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 678
    def references( default = nil )
      if h = @header['references']
        h.refs
      else
        default
      end
    end

references=( *strs ) click to toggle source

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

    # File lib/tmail/interface.rb, line 695
    def references=( *strs )
      set_string_array_attr 'References', strs
    end

reply_addresses( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 1080
    def reply_addresses( default = nil )
      reply_to_addrs(nil) or from_addrs(nil) or default
    end

reply_to( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 454
    def reply_to( default = nil )
      addrs2specs(reply_to_addrs(nil)) || default
    end

reply_to=( *strs ) click to toggle source

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

    # File lib/tmail/interface.rb, line 467
    def reply_to=( *strs )
      set_string_array_attr 'Reply-To', strs
    end

reply_to_addrs( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 424
    def reply_to_addrs( default = nil )
      if h = @header['reply-to']
        h.addrs.blank? ? default : h.addrs
      else
        default
      end
    end

reply_to_addrs=( arg ) click to toggle source

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

    # File lib/tmail/interface.rb, line 442
    def reply_to_addrs=( arg )
      set_addrfield 'reply-to', arg
    end

send_text_to( smtp ) click to toggle source

    # File lib/tmail/net.rb, line 41
    def send_text_to( smtp )
      do_send_to(smtp) do
        ready_to_send
        mime_encode
      end
    end

send_to( smtp ) click to toggle source

    # File lib/tmail/net.rb, line 35
    def send_to( smtp )
      do_send_to(smtp) do
        ready_to_send
      end
    end

send_to_0( smtp, from, to ) click to toggle source

    # File lib/tmail/net.rb, line 56
    def send_to_0( smtp, from, to )
      smtp.ready(from, to) do |f|
        encoded "\r\n", 'j', f, ''
      end
    end

sender( default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 517
    def sender( default = nil )
      f = @header['sender'] or return default
      a = f.addr            or return default
      a.spec
    end

sender=( str ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 532
    def sender=( str )
      set_string_attr 'Sender', str
    end

sender_addr( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 483
    def sender_addr( default = nil )
      f = @header['sender'] or return default
      f.addr                or return default
    end

sender_addr=( addr ) click to toggle source

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

    # File lib/tmail/interface.rb, line 498
    def sender_addr=( addr )
      if addr
        h = HeaderField.internal_new('sender', @config)
        h.addr = addr
        @header['sender'] = h
      else
        @header.delete 'sender'
      end
      addr
    end

set_content_disposition( str, params = nil ) click to toggle source
Alias for: set_disposition
set_content_type( str, sub = nil, param = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 814
    def set_content_type( str, sub = nil, param = nil )
      if sub
        main, sub = str, sub
      else
        main, sub = str.split(%</>, 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

Also aliased as: content_type=
set_disposition( str, params = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 973
    def set_disposition( str, params = nil )
      if h = @header['content-disposition']
        h.disposition = str
        h.params.clear
      else
        store('Content-Disposition', str)
        h = @header['content-disposition']
      end
      h.params.replace params if params
    end

Also aliased as: disposition=, set_content_disposition, content_disposition=
store( key, val ) click to toggle source
Alias for: []=
strftime( fmt, default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 148
    def strftime( fmt, default = nil )
      if t = date
        t.strftime(fmt)
      else
        default
      end
    end

sub_header(key, param) click to toggle source

    # File lib/tmail/mail.rb, line 251
    def sub_header(key, param)
      (hdr = self[key]) ? hdr[param] : nil
    end

sub_type( default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 787
    def sub_type( default = nil )
      if h = @header['content-type']
        h.sub_type || default
      else
        default
      end
    end

subject( default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 550
    def subject( default = nil )
      if h = @header['subject']
        h.body
      else
        default
      end
    end

Also aliased as: quoted_subject
subject=( str ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 567
    def subject=( str )
      set_string_attr 'Subject', str
    end

text_content_type?() click to toggle source

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

    # File lib/tmail/attachments.rb, line 23
    def text_content_type?
      self.header['content-type'] && (self.header['content-type'].main_type == 'text')
    end

to( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 268
    def to( default = nil )
      addrs2specs(to_addrs(nil)) || default
    end

to=( *strs ) click to toggle source

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

    # File lib/tmail/interface.rb, line 305
    def to=( *strs )
      set_string_array_attr 'To', strs
    end

to_addrs( default = nil ) click to toggle source

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

    # File lib/tmail/interface.rb, line 170
    def to_addrs( default = nil )
      if h = @header['to']
        h.addrs
      else
        default
      end
    end

to_addrs=( arg ) click to toggle source

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

    # File lib/tmail/interface.rb, line 228
    def to_addrs=( arg )
      set_addrfield 'to', arg
    end

transfer_encoding( default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 916
    def transfer_encoding( default = nil )
      if h = @header['content-transfer-encoding']
        h.encoding || default
      else
        default
      end
    end

Also aliased as: encoding, content_transfer_encoding
transfer_encoding=( str ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 935
    def transfer_encoding=( str )
      set_string_attr 'Content-Transfer-Encoding', str
    end

Also aliased as: encoding=, content_transfer_encoding=
type_param( name, default = nil ) click to toggle source

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"

    # File lib/tmail/interface.rb, line 844
    def type_param( name, default = nil )
      if h = @header['content-type']
        h[name] || default
      else
        default
      end
    end

values_at( *args ) click to toggle source

    # File lib/tmail/mail.rb, line 379
    def values_at( *args )
      args.map {|k| @header[k.downcase] }.flatten
    end

Also aliased as: indexes, indices
write_back( eol = "\n", charset = 'e' ) click to toggle source

    # File lib/tmail/mail.rb, line 164
    def write_back( eol = "\n", charset = 'e' )
      parse_body
      @port.wopen {|stream| encoded eol, charset, stream }
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.