Ruby 1.8.7 リファレンスマニュアル > ライブラリ一覧 > net/imapライブラリ

library net/imap

要約

このライブラリは Internet Message Access Protocol (IMAP) の クライアントライブラリです。[RFC2060] を元に 実装されています。

IMAP の概要

IMAPを利用するには、まずサーバに接続し、 Net::IMAP#authenticate もしくは Net::IMAP#login で認証します。 IMAP ではメールボックスという概念が重要です。 メールボックスは階層的な名前を持ちます。 各メールボックスはメールを保持することができます。 メールボックスの実装はサーバソフトウェアによって異なります。 Unixシステムでは、ディレクトリ階層上の ファイルを個々のメールボックスとみなして実装されることが多いです。

メールボックス内のメッセージ(メール)を処理する場合、 まず Net::IMAP#select もしくは Net::IMAP#examine で処理対象のメールボックスを 指定する必要があります。これらの操作が成功したならば、 「selected」状態に移行し、そのメールボックスが「処理対象の」 メールボックスとなります。このようにしてメールボックスを 選択してから、selected状態を終える(別のメールボックスを選択したり、 接続を終了したり)までをセッションと呼びます。

メッセージには2種類の識別子が存在します。message sequence number と UID です。

message sequence number はメールボックス内の各メッセージに1から順に 振られた番号です。セッション中に処理対象のメールボックスに 新たなメッセージが追加された場合、そのメッセージの message sequence number は 最後のメッセージの message sequence number+1となります。 メッセージをメールボックスから消した場合には、連番の穴を埋めるように message sequence number が付け替えられます。

一方、UID はセッションを越えて恒久的に保持されます。 あるメールボックス内の異なる2つのメッセージが同じ UID を持つことはありません。 これは、メッセージがメールボックスから削除された後でも成立します。

しかし、UID はメールボックス内で昇順であることが 規格上要請されているので、 IMAP を使わないメールアプリケーションがメールの順番を 変えてしまった場合は、UID が振り直されます。

デフォルトのメールボックス(INBOX)の送り元とサブジェクトを表示する。

imap = Net::IMAP.new('mail.example.com')
imap.authenticate('LOGIN', 'joe_user', 'joes_password')
imap.examine('INBOX')
imap.search(["RECENT"]).each do |message_id|
  envelope = imap.fetch(message_id, "ENVELOPE")[0].attr["ENVELOPE"]
  puts "#{envelope.from[0].name}: \t#{envelope.subject}"
end

2003年4月のメールをすべて Mail/sent-mail から "Mail/sent-apr03" へ移動させる

imap = Net::IMAP.new('mail.example.com')
imap.authenticate('LOGIN', 'joe_user', 'joes_password')
imap.select('Mail/sent-mail')
if not imap.list('Mail/', 'sent-apr03')
  imap.create('Mail/sent-apr03')
end
imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_id|
  imap.copy(message_id, "Mail/sent-apr03")
  imap.store(message_id, "+FLAGS", [:Deleted])
end
imap.expunge

スレッド安全性

Net::IMAP は並列実行をサポートしています。例として、

imap = Net::IMAP.new("imap.foo.net", "imap2")
imap.authenticate("cram-md5", "bar", "password")
imap.select("inbox")
fetch_thread = Thread.start { imap.fetch(1..-1, "UID") }
search_result = imap.search(["BODY", "hello"])
fetch_result = fetch_thread.value
imap.disconnect

とすると FETCH コマンドと SEARCH コマンドを並列に実行します。

エラーについて

IMAP サーバは以下の3種類のエラーを送ります。

NO

コマンドが正常に完了しなかったことを意味します。 例えば、ログインでのユーザ名/パスワードが間違っていた、 選択したメールボックスが存在しない、などです。

BAD

クライアントからのリクエストをサーバが理解できなかった ことを意味します。 クライアントの現在の状態では使えないコマンドを使おうとした 場合にも発生します。例えば、 selected状態(SELECT/EXAMINEでこの状態に移行する)にならずに SEARCH コマンドを使おうとした場合に発生します。 サーバの内部エラー(ディスクが壊れたなど)の場合も このエラーが発生します。

BYE

サーバが接続を切ろうとしていることを意味します。 これは通常のログアウト処理で発生します。 また、ログイン時にサーバが(なんらかの理由で)接続 したくない場合にも発生します。 それ以外では、サーバがシャットダウンする場合か サーバがタイムアウトする場合に発生します。

これらのエラーはそれぞれ

という例外クラスに対応しています。 原理的には、これらの例外はサーバにコマンドを送った場合には 常に発生する可能性があります。しかし、このドキュメントでは よくあるエラーのみ解説します。

IMAP は Socket で通信をするため、IMAPクラスのメソッドは Socket 関連のエラーが発生するかもしれません。例えば、 通信中に接続が切れると Errno::EPIPE 例外が 発生します。詳しくは Socket などを見てください。

Net::IMAP::DataFormatErrorNet::IMAP::ResponseParseError という例外クラスも 存在します。前者はデータのフォーマットが正しくない場合に、 後者はサーバからのレスポンスがパースできない場合に発生します。 これらのエラーはこのライブラリもしくはサーバに深刻な問題が あることを意味します。

tagged response と untagged response

IMAP プロトコルにおいてサーバからの応答には tagged なものと untagged なものの2通り存在します。 tagged な応答は、クライアントからのコマンドが 成功もしくは失敗のいずれかで完了したことを表すものです。 一方 untagged な応答はそれ以外の情報を渡すためのものです。 untagged な応答はクライアントからのコマンドの結果の情報を 渡すためにも用いられますし、そうでない(サーバのシャットダウンなど) 自発的応答にも用いられます。

これはそれぞれ Net::IMAP::TaggedResponseNet::IMAP::UntaggedResponse に対応します。

untagged な応答はコマンドの送信とは非同期的にサーバから送られるため、 Net::IMAP オブジェクトはユーザのためこれを Net::IMAP#responses に記録しておきます。

References

以上のうち、いくつかの RFC は obsolete になって置き換えられています。 [RFC2060][RFC3501] に、[RFC822][RFC2822] に、 置き換えられています。

クラス

Net::IMAP

IMAP 接続を表現するクラスです。

Net::IMAP::FetchData

FETCH コマンドの応答を表すクラスです。

Net::IMAP::Address

メールアドレスを表すクラスです。

Net::IMAP::BodyTypeBasic

text 型(Net::IMAP::BodyTypeText)、 multipart 型(Net::IMAP::BodyTypeMultipart)、 message 型(Net::IMAP::BodyTypeMessage)、 のいずれでもないようなメッセージボディ構造を表すクラスです。

Net::IMAP::BodyTypeMessage

Content-Type が "message" であるメッセージを表すクラスです。

Net::IMAP::BodyTypeMultipart

マルチパートなメッセージを表すクラスです。

Net::IMAP::BodyTypeText

Content-Type が text であるメッセージを表すクラスです。

Net::IMAP::ContentDisposition

[RFC1806], [RFC2183] で定義されている MIME の Content-Disposition フィールドを表すクラスです。

Net::IMAP::ContinuationRequest

IMAP の continuation request (命令継続要求) を表すクラスです。

Net::IMAP::Envelope

メッセージのエンベロープを表すクラスです。

Net::IMAP::MailboxACLItem

GETACL の応答の各要素を表すクラスです。

Net::IMAP::MailboxList

Net::IMAP#listNet::IMAP#lsub で返されるメールボックスのデータを表します。

Net::IMAP::MailboxQuota

Net::IMAP#getquotaNet::IMAP#getquotaroot で得られる quota の情報を表すオブジェクトです。

Net::IMAP::MailboxQuotaRoot

Net::IMAP#getquotaroot の結果として得られる quota root 情報を表わすオブジェクトです。

Net::IMAP::ResponseCode

応答のレスポンスコードを表すクラスです。

Net::IMAP::ResponseText

応答のテキストを表すクラスです。

Net::IMAP::StatusData

STATUS 応答を表わすクラスです。

Net::IMAP::TaggedResponse

IMAP のタグ付きレスポンスを表すクラスです。

Net::IMAP::ThreadMember

Net::IMAP#threadNet::IMAP#uid_thread から 得られるスレッドの木構造のノードを表すクラスです。

Net::IMAP::UntaggedResponse

IMAP のタグ付きレスポンスを表すクラスです。

例外クラス

Net::IMAP::Error

すべての IMAP 例外クラスのスーパークラス。

  Net::IMAP::DataFormatError

データフォーマットが正しくない場合に発生する例外のクラスです。

  Net::IMAP::ResponseError

サーバからのレスポンスがエラーを示している場合に発生する例外 のクラスです。

   Net::IMAP::BadResponseError

サーバから "BAD" レスポンスが来た場合に発生する例外のクラスです。 クライアントからのコマンドが IMAP の規格から外れている場合や サーバ内部エラーの場合に発生します。

   Net::IMAP::ByeResponseError

サーバから "BYE" レスポンスが来た場合に発生する例外のクラスです。 ログインが拒否された場合や、クライアントが無反応で タイムアウトした場合に発生します。

   Net::IMAP::NoResponseError

サーバから "NO" レスポンスが来た場合に発生する例外のクラスです。 コマンドが正常に完了しなかった場合に発生します。

  Net::IMAP::ResponseParseError

サーバからのレスポンスが正しくパースできない場合に発生する 例外のクラスです。