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.