TMail の使い方

TMail の概要

TMail は電子メールを扱うための総合ライブラリです。メールとメールボックスのハンドリングを隠蔽します。初期の目的がメーラの作成だったため、主な使い方としては「メールから情報を得る」「新しいメールを作成する」の二種類が想定されており、クライアント側の処理に強くなっています。

メールから情報を得る

これは一番最初に実装された部分であり、TMail が最も得意とする処理でもあります。

TMail::Mail クラス

TMail::Mail クラスはメール一通を隠蔽するオブジェクトです。まずどうにかしてこのオブジェクトを作らないといけません。このオブジェクトを作る方法は三通りあります。

文字列からつくる
ファイル(名)からつくる
Port からつくる

文字列、ファイルはそれぞれメール一通分だけを含んでいなければいけません。そのうえで以下のように作成します。

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

ここには特に問題はないと思います。

Port と Loader

Port というのは TMail におけるメールソースの抽象表現です。たとえば上述した文字列やファイル名もメールソースで、TMail::Mail#parse や load は文字列やファイルを一度 Port でラップしたうえで Mail オブジェクトを作成しています。この Port でラップすることで文字列、ファイル (将来的には IMAP プロトコルも？) の違いを隠蔽しています。

ただし、Port をユーザが直接作ることはあまりないでしょう。主にユーザが Port をさわることになるのは、メールボックスのラッパーである Loader を使うときです。たとえば MH メールボックスの中にあるメールを順番に処理するためには以下のようにします。

require 'tmail'

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

TMail::Mail オブジェクトから情報を得る

以上のような手段で TMail::Mail オブジェクトを作ったら、あとはそのメソッドを呼ぶだけでたいていのことはできます。たとえば To: アドレスを取るなら

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

Subject: ならば

p mail.subject

メール本体ならばというように、とても簡単です。

詳しくは TMail::Mail クラスのリファレンスを、より実用的な例としては sample/from-check.rb を見てください。

MIME マルチパートメール

MIME マルチパートメールにも対応しています。マルチパートのときは Mail#multipart? が真になり、#parts に TMail::Mail オブジェクトの配列が入ります。

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

より具体的な例としては sample/multipart.rb を見てください。

TMail がやらないこと

TMail は、ヘッダは自動でデコード・エンコードしますが、本体(本文)は一切変更しません。ただし近い将来には Base64 のデコードは自動でやるかもしれません。

新しいメールを作成する

こちらも TMail::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 )

作ったら、中身を入れます。

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

どのヘッダをセットしたらいいかなど細かい部分ももうちょっとカバーしたいのですが、まだ実装していません。とりあえず上記のヘッダはセットしたほうがよいでしょう。また返信・転送の場合はまたそれぞれ規約があります。これもカバーしたいのですがまだ実装していません。バージョン 1.0 に期待してください。

最後に文字列化します。

str = mail.encoded

作成元ポートに書き戻すなら、かわりに以下のようにします。

mail.write_back

write_back は中間文字列を介することなくファイルに直接書きこみます。

より実用的な例としては sample/sendmail.rb を見てください。