# TMail Usage

## Abstruction

TMail is 90% RFC compatible mail library. By using TMail, You can get data from internet mail (e-mail) and write data to mail, without knowning standard details.

## Getting information from e-mail

### class TMail::Mail

At first you must create TMail::Mail object. There's three ways to create Mail object. First one is "creating from string", second way is "creating from file (name)". Examples are below:

    require 'tmail'
    mail = TMail::Mail.parse(string)    # from String
    mail = TMail::Mail.load(filename)   # from file

### Port and Loader

The third way to get TMail::Mail object is using the "port". "port" is the abstruction of mail sources, e.g. strings or file names. You can get ports by using mail loaders (TMail::*Loader classes). Here's simple example:

    require 'tmail'

    loader = TMail::MhLoader.new( '/home/aamine/Mail/inbox' )
    loader.each_port do |port|
      mail = TMail::Mail.new(port)
      # ....
    end

### Accessing EMail Attributes via TMail::Mail object

Now you can get any data from e-mail, by calling methods of TMail::Mail object. For example, to get To: addresses...

    require 'tmail'
    mail = TMail::Mail.parse( 'To: Minero Aoki <aamine@loveruby.net>' )
    p mail.to   # => ["aamine@loveruby.net"]

to get subject,

    p mail.subject

to get mail body,

    p mail.body

For more TMail::Mail class details, see reference manual. For more examples, see sample/from-check.rb.

### MIME multipart mail

TMail also supports MIME multipart mails. If mail is multipart mail, Mail#multipart? returns true, and Mail#parts contains an array of parts (TMail::Mail object).

    require 'tmail'
    mail = TMail::Mail.parse( multipart_mail_string )
    if mail.multipart? then
      mail.parts.each do |m|
        puts m.main_type
      end
    end

For examples, see sample/multipart.rb.

### What TMail is NOT

TMail does not touch mail body. Does not decode body, does not encode body, does not change line terminator. (I want to support Base64 auto-decoding although.)

## Creating New Mail

    require 'tmail'

    # Example 1: create mail on only memory
    mail = TMail::Mail.new

    # Example 2: create mail on mailbox (on disk)
    loader = TMail::MhLoader.new('/home/aamine/Mail/drafts')
    mail = TMail::Mail.new( loader.new_port )

then fill headers and body.

    mail.to = 'test@loveruby.net'
    mail.from = 'Minero Aoki <aamine@loveruby.net>'
    mail.subject = 'test mail'
    mail.date = Time.now
    mail.mime_version = '1.0'
    mail.set_content_type 'text', 'plain', {'charset'=>'iso-2022-jp'}
    mail.body = 'This is test mail.'

At last, convert mail object to string.

    str = mail.encoded

If you want to write mails against files directly (without intermediate string), use Mail#write_back.

    mail.write_back

For more examples, see sample/sendmail.rb.