class Net::IMAP (Ruby 4.0 リファレンスマニュアル)

要約

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

特異メソッド

add_authenticator(auth_type, authenticator) -> ()[permalink][rdoc][edit]

Net::IMAP#authenticate で使う認証用クラスを設定します。

imap ライブラリに新たな認証方式を追加するために用います。

通常は使う必要はないでしょう。もしこれを用いて認証方式を追加する場合は net/imap.rb の Net::IMAP::LoginAuthenticator などを参考にしてください。

[PARAM] auth_type:: 認証の種類(文字列)
[PARAM] authenticator:: 認証クラス(Class オブジェクト)

config -> Net::IMAP::ConfigRuby 3.4 から[permalink][rdoc][edit]

全体の設定 Net::IMAP::Config.global を返します。

Net::IMAP.new で config を省略すると、接続ごとの設定 Net::IMAP#config はこの設定を継承します。

例

require 'net/imap'

p Net::IMAP.config.equal?(Net::IMAP::Config.global) # => true
p Net::IMAP.config.open_timeout                     # => 30

[SEE_ALSO] Net::IMAP::Config, Net::IMAP#config

debug -> bool[permalink][rdoc][edit]

デバッグモードが on になっていれば真を返します。

全体の設定 Net::IMAP::Config#debug の値を返します。

[SEE_ALSO] Net::IMAP.debug=

debug=(val)[permalink][rdoc][edit]

デバッグモードの on/off をします。

真を渡すと on になります。

全体の設定 Net::IMAP::Config#debug= に設定します。

[PARAM] val:: 設定するデバッグモードの on/off の真偽値

[SEE_ALSO] Net::IMAP.debug

decode_utf7(str) -> String[permalink][rdoc][edit]

modified UTF-7 の文字列を UTF-8 の文字列に変換します。

modified UTF-7 は IMAP のメールボックス名に使われるエンコーディングで、 UTF-7 を修正したものです。

詳しくは [RFC2060] の 5.1.3 を参照してください。

Net::IMAP ではメールボックス名のエンコードを自動的変換「しない」ことに注意してください。必要があればユーザが変換すべきです。

[PARAM] str:: 変換対象の modified UTF-7 でエンコードされた文字列

[SEE_ALSO] Net::IMAP.encode_utf7

default_port -> IntegerRuby 2.0.0 から[permalink][rdoc][edit]

default_imap_port -> Integer

デフォルトの IMAP のポート番号(143)を返します。

[SEE_ALSO] Net::IMAP.default_tls_port

default_tls_port -> IntegerRuby 2.0.0 から[permalink][rdoc][edit]

default_imaps_port -> Integer

default_ssl_port -> Integer

デフォルトの IMAPS のポート番号(993)を返します。

[SEE_ALSO] Net::IMAP.default_port

encode_utf7(str) -> String[permalink][rdoc][edit]

UTF-8 の文字列を modified UTF-7 の文字列に変換します。

modified UTF-7 は IMAP のメールボックス名に使われるエンコーディングで、 UTF-7 を修正したものです。

詳しくは Net::IMAP.encode_utf7 を見てください。

[PARAM] str:: 変換対象の UTF-8 でエンコードされた文字列

[SEE_ALSO] Net::IMAP.decode_utf7

format_date(time) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

時刻オブジェクトを IMAP の日付フォーマットでの文字列に変換します。

require 'net/imap'

p Net::IMAP.format_date(Time.new(2011, 6, 20))
# => "20-Jun-2011"

[PARAM] time:: 変換する時刻オブジェクト

format_datetime(time) -> StringRuby 1.9.3 から[permalink][rdoc][edit]

時刻オブジェクトを IMAP の日付時刻フォーマットでの文字列に変換します

require 'net/imap'

p Net::IMAP.format_datetime(Time.new(2011, 6, 20, 13, 20, 1))
# => "20-Jun-2011 13:20 +0900"

[PARAM] time:: 変換する時刻オブジェクト

new(host, port: nil, ssl: nil, response_handlers: nil, config: Net::IMAP::Config.global, **config_options) -> Net::IMAP[permalink][rdoc][edit]

新たな Net::IMAP オブジェクトを生成し、指定したホストの指定したポートに接続し、接続後の IMAP オブジェクトを返します。

ssl に真を渡すと、サーバに繋ぐのに SSL/TLS を用います。 ssl がハッシュならば、それを OpenSSL::SSL::SSLContext#set_params に渡して SSL/TLS のパラメータを設定します。ハッシュでない真の値(true など)ならば、空のハッシュを渡したのと同じで、OpenSSL::SSL::SSLContext#set_params の既定のパラメータを使います。ハッシュへの変換は Hash.try_convert で行うので、to_hash を持つオブジェクトもハッシュとして扱います。 SSL/TLS での接続には OpenSSL と openssl が使える必要があります。 port を省略すると、SSL/TLS を使うときは 993、使わないときは 143 に接続します。

response_handlers には受信スレッドを開始する前に追加する応答ハンドラのリストを指定します。こうすると最初の応答(Net::IMAP#greeting)も含めて、サーバからのすべての応答がハンドラで処理されます。

config には接続の設定(Net::IMAP::Config オブジェクト)を指定します。設定のほかに、版の数値(0.4 など)や名前(:current など)やハッシュも Net::IMAP::Config.[] と同じように指定できます。これは接続ごとに作られる設定(Net::IMAP#config)を直接置き換えるのではなく、その継承元になります。省略時は全体の設定 Net::IMAP::Config.global が継承元になります。残りのキーワード引数 config_options は Net::IMAP::Config.new に渡され、接続ごとの設定の初期値になります。たとえば open_timeout(接続が確立するまで待つ秒数。既定値は 30)や idle_response_timeout(IDLE の応答を待つ秒数。既定値は 5)を指定できます。

互換性のため、Net::IMAP.new(host, port) と Net::IMAP.new(host, options)(options はハッシュ)の形も受け付けます。それぞれ port を port: のキーワード引数に、options をキーワード引数に変換し、警告は出ません。 Net::IMAP.new(host, port, usessl, certs, verify) の形は非推奨で、警告を出します。 usessl が偽ならば certs と verify は無視され、SSL/TLS を使いません。 usessl が真ならば certs と verify を ssl のハッシュに変換します。 certs がファイルならば ca_file に、ディレクトリならば ca_path に変換し、verify が真ならば verify_mode に OpenSSL::SSL::VERIFY_PEER を、偽ならば OpenSSL::SSL::VERIFY_NONE を設定します。

例

require 'net/imap'

imap = Net::IMAP.new('imap.example.com', port: 993,
                     ssl: { verify_mode: OpenSSL::SSL::VERIFY_PEER,
                            timeout: 600 })

この警告は Warning[:deprecated] が真のとき(-W:deprecated を指定したときなど)だけ表示されます。

[PARAM] host:: 接続するホスト名の文字列
[PARAM] port:: 接続するポート番号
[PARAM] ssl:: 真で SSL/TLS を使う。ハッシュなら OpenSSL::SSL::SSLContext#set_params に渡すパラメータ(ハッシュでない真の値は既定のパラメータ)
[PARAM] response_handlers:: 受信スレッドを開始する前に追加する応答ハンドラのリスト
[PARAM] config:: 接続ごとの設定の継承元とする Net::IMAP::Config オブジェクト。版の数値や名前やハッシュも指定できます
[PARAM] config_options:: 接続ごとの設定の初期値(open_timeout など)
[EXCEPTION] ArgumentError:: 互換のための形の引数とキーワード引数を同時に渡した場合や、options のハッシュと usessl などを同時に渡した場合に発生します

インスタンスメソッド

add_response_handler(handler) -> ()[permalink][rdoc][edit]

add_response_handler(handler) {|resp| ...} -> ()

レスポンスハンドラを追加します。

レスポンスハンドラはサーバから応答を受け取るごとに呼びだされます。ハンドラには Net::IMAP::TaggedResponse もしくは Net::IMAP::UntaggedResponse オブジェクトが渡されます。

主にサーバからの非同期的なイベントを受け取るために用います。例えば EXISTS 応答を受け取る (メールボックスに新たなメールが追加されたタイミングで発生します) ためなどに用いられます。

レスポンスハンドラはメインのスレッドとは別のスレッドで呼びだされることに注意してください。

例

imap.add_response_handler do |resp|
  p resp
end

[PARAM] handler:: 追加するハンドラ(Proc や Method オブジェクト)

[SEE_ALSO] Net::IMAP#remove_response_handler

append(mailbox, message, flags = nil, date_time = nil) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

APPEND コマンドを送ってメッセージをメールボックスの末尾に追加します。

例

imap.append("inbox", <<EOF.gsub(/\n/, "\r\n"), [:Seen], Time.now)
Subject: hello
From: someone@example.com
To: somebody@example.com
  
hello world
EOF

[PARAM] mailbox:: メッセージを追加するメールボックス名(文字列)
[PARAM] message:: メッセージ文字列
[PARAM] flags:: メッセージに付加するフラグ(Symbol の配列)
[PARAM] date_time:: メッセージの時刻(Time オブジェクト)。省略時は現在時刻が使われる
[EXCEPTION] Net::IMAP::NoResponseError:: メールボックスが存在しない場合に発生します

authenticate(mechanism, *creds, sasl_ir: true, **props) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

AUTHENTICATE コマンドを送り、クライアントを認証します。

mechanism で利用する SASL の認証方式を文字列で指定します。残りの引数とブロックはその認証方式の実装にそのまま渡されます。渡す認証情報(ユーザ名、パスワード、アクセストークンなど)は認証方式ごとに異なります。

例

imap.authenticate('PLAIN', user, password)

mechanism としては以下がサポートされています。

"ANONYMOUS"
"EXTERNAL"
"OAUTHBEARER"
"PLAIN"
"SCRAM-SHA-1"
"SCRAM-SHA-256"
"XOAUTH2"
"LOGIN"(非推奨)
"CRAM-MD5"(非推奨)
"DIGEST-MD5"(非推奨)

非推奨の認証方式は互換性のために残されているもので、使うと警告を出します。 "LOGIN" の代わりには "PLAIN" を使います。 "XOAUTH2" は非標準で "OAUTHBEARER" に置き換えられたものですが、広く使われています。

サーバが SASL-IR 拡張([RFC4959])と指定した認証方式に対応していて、認証方式がクライアントから先に応答するものであれば、sasl_ir が真のときは最初の応答を AUTHENTICATE コマンドの引数として送り、往復を 1 回省きます。

sasl_ir の既定値は接続の設定 Net::IMAP::Config#sasl_ir の値で、その既定値は true です。

[PARAM] mechanism:: 認証方式を表す文字列
[PARAM] creds:: 認証方式の実装に渡す認証情報。認証方式ごとに異なります
[PARAM] sasl_ir:: 偽を指定すると最初の応答を AUTHENTICATE コマンドの引数として送りません
[PARAM] props:: 認証方式の実装に渡すキーワード引数。認証方式ごとに異なります

[SEE_ALSO] Net::IMAP#login

capability -> [String][permalink][rdoc][edit]

CAPABILITY コマンドを送ってサーバがサポートしている機能(capabilities)のリストを文字列の配列として返します。

capability は IMAP に関連する RFC などで定義されています。

p imap.capability
# => ["IMAP4REV1", "UNSELECT", "IDLE", "NAMESPACE", "QUOTA", ... ]

check -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

CHECK コマンドを送り、現在処理しているメールボックスのチェックポイントを要求します。

チェックポイントの要求とは、サーバ内部で保留状態になっている操作を完了させることを意味します。例えばメモリ上にあるメールのデータをディスクに書き込むため、fsyncを呼んだりすることです。実際に何が行なわれるかはサーバの実装によりますし、何も行なわれない場合もあります。

close -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

CLOSE コマンドを送り、処理中のメールボックスを閉じます。

このコマンドによって、どのメールボックスも選択されていない状態に移行します。そして \Deleted フラグが付けられたメールがすべて削除されます。

config -> Net::IMAP::ConfigRuby 3.4 から[permalink][rdoc][edit]

接続ごとの設定を返します。

この設定は Net::IMAP.new で接続ごとに作られ、config で指定した設定(省略時は全体の設定 Net::IMAP.config)を継承します。 Net::IMAP.new の残りのキーワード引数が、この設定の初期値になります。

[SEE_ALSO] Net::IMAP::Config, Net::IMAP.config

copy(set, mailbox) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

COPY コマンドを送り、指定したメッセージを指定したメールボックスの末尾に追加します。

set でコピーするメッセージを指定します。 message sequence number(整数)、 message sequence numberの配列、もしくは Range で指定します。コピー元のメールボックスは Net::IMAP#examine もしくは Net::IMAP#select で指定したものを用います。 mailbox はコピー先のメールボックスです。

[PARAM] set:: コピーするメッセージの message sequence number
[PARAM] mailbox:: コピー先のメールボックス(文字列)

[SEE_ALSO] Net::IMAP#uid_copy

create(mailbox) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

CREATE コマンドを送り、新しいメールボックスを作ります。

[PARAM] mailbox:: 新しいメールボックスの名前(文字列)
[EXCEPTION] Net::IMAP::NoResponseError:: 指定した名前のメールボックスが作れなかった場合に発生します

delete(mailbox) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

DELETE コマンドを送り、指定したメールボックスを削除します。

[PARAM] mailbox:: 削除するメールボックスの名前(文字列)
[EXCEPTION] Net::IMAP::NoResponseError:: 指定した名前のメールボックスを削除できなかった場合に発生します。指定した名前のメールボックスが存在しない場合や、ユーザにメールボックスを削除する権限がない場合に発生します。

disconnect -> nil[permalink][rdoc][edit]

サーバとの接続を切断します。

[SEE_ALSO] Net::IMAP#disconnected?

disconnected? -> bool[permalink][rdoc][edit]

サーバとの接続が切断されていれば真を返します。

[SEE_ALSO] Net::IMAP#disconnect

examine(mailbox, condstore: false) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

EXAMINE コマンドを送り、指定したメールボックスを処理対象のメールボックスにします。

Net::IMAP#select と異なりセッション中はメールボックスが読み取り専用となります。それ以外は select と同じです。

[PARAM] mailbox:: 処理対象としたいメールボックスの名前(文字列)
[PARAM] condstore:: 真を指定すると CONDSTORE 拡張([RFC7162])を有効にします。メールボックスが mod-sequence の保持に対応していれば HIGHESTMODSEQ 応答コードが untagged な応答として送られ、以後の FETCH の応答に mod-sequence が含まれます。
[EXCEPTION] Net::IMAP::NoResponseError:: mailboxが存在しない等の理由でコマンドの実行に失敗した場合に発生します。

expunge -> [Integer] | nil[permalink][rdoc][edit]

EXPUNGEコマンドを送り、:Deletedフラグをセットしたメッセージをすべて処理中のメールボックスから削除します。

削除したメッセージの message sequence number を配列で返します。

[EXCEPTION] Net::IMAP::NoResponseError:: メールボックスが read-only である場合に発生します

fetch(set, attr, changedsince: nil) -> [Net::IMAP::FetchData][permalink][rdoc][edit]

FETCH コマンドを送り、メールボックス内のメッセージに関するデータを取得します。

Net::IMAP#examine もしくは Net::IMAP#select で指定したメールボックスを対象とします。

set で対象とするメッセージを指定します。これには sequence number、sequence number の配列、もしくは Range オブジェクトを渡します。 attr には取得するアトリビュートを文字列の配列で渡してください。指定可能なアトリビュートについては Net::IMAP::FetchData#attr を見てください。

例

p imap.fetch(6..8, "UID")
# => [#<Net::IMAP::FetchData seqno=6, attr={"UID" => 98}>, #<Net::IMAP::FetchData seqno=7, attr={"UID" => 99}>, #<Net::IMAP::FetchData seqno=8, attr={"UID" => 100}>]
p imap.fetch(6, "BODY[HEADER.FIELDS (SUBJECT)]")
# => [#<Net::IMAP::FetchData seqno=6, attr={"BODY[HEADER.FIELDS (SUBJECT)]" => "Subject: test\r\n\r\n"}>]
data = imap.uid_fetch(98, ["RFC822.SIZE", "INTERNALDATE"])[0]
p data.seqno
# => 6
p data.attr["RFC822.SIZE"]
# => 611
p data.attr["INTERNALDATE"]
# => "12-Oct-2000 22:40:59 +0900"
p data.attr["UID"]
# => 98

[PARAM] set:: 処理対象のメッセージの sequence number
[PARAM] attr:: アトリビュート(文字列配列)
[PARAM] changedsince:: mod-sequence を整数で指定すると、mod-sequence がそれより大きいメッセージだけを対象にします。指定すると CONDSTORE 拡張([RFC7162])を暗黙に有効にします。

[SEE_ALSO] Net::IMAP#uid_fetch

getacl(mailbox) -> [Net::IMAP::MailboxACLItem][permalink][rdoc][edit]

GETACL コマンドを送り、メールボックスの ACL(Access Control List) を取得します。

Net::IMAP#getacl で指定したメールボックスに対し何らかの権限を持つ各ユーザに対して Net::IMAP::MailboxACLItem オブジェクトが作られ、その配列が返されます。

GETACL コマンドは [RFC2086] で定義されています。詳しくはそちらを参照してください。

[PARAM] mailbox:: メールボックス名(文字列)

[SEE_ALSO] Net::IMAP::MailboxACLItem

getquota(mailbox) -> [Net::IMAP::MailboxQuota][permalink][rdoc][edit]

GETQUOTA コマンドを送って指定したメールボックスの quota の情報を返します。

quota の情報は Net::IMAP::MailboxQuota オブジェクトの配列で得られます。

詳しくは [RFC2087] を見てください。このコマンドは Net::IMAP#capability の返り値を見ることで利用可能かどうか判断できます。

[PARAM] mailbox:: quota 情報を得たいメールボックス名
[EXCEPTION] Net::IMAP::NoResponseError:: 指定したメールボックスが quota root でない場合に発生します

getquotaroot(mailbox) -> [Net::IMAP::MailboxQuotaRoot | Net::IMAP::MailboxQuota][permalink][rdoc][edit]

GETQUOTAROOT コマンドを送って指定したメールボックスの quota root の一覧と、関連する quota の情報を返します。

quota root の情報は Net::IMAP::MailboxQuotaRoot のオブジェクトで、返り値の配列の中に唯一含まれています。 quota の情報はメールボックスに関連付けられた quota root ごとに Net::IMAP::MailboxQuota オブジェクトで得られます。

詳しくは [RFC2087] を見てください。このコマンドは Net::IMAP#capability の返り値を見ることで利用可能かどうか判断できます。

[PARAM] mailbox:: quota root を得たいメールボックス名(文字列)
[EXCEPTION] Net::IMAP::NoResponseError:: 指定したメールボックスが存在しない場合に発生します

greeting -> Net::IMAP::UntaggedResponse[permalink][rdoc][edit]

サーバから最初に送られてくるメッセージ(greeting message) を返します。

idle {|resp| ...} -> Net::IMAP::TaggedResponseRuby 1.9.3 から[permalink][rdoc][edit]

IDLE 命令を送り、メールボックスの非同期的変化を待ち受けます。

このメソッドに渡したブロックは Net::IMAP#add_response_handler によってレスポンスハンドラとして用いられます。また、このメソッドが終了する時点で Net::IMAP#remove_response_handler でハンドラが削除されます。

レスポンスハンドラについては Net::IMAP#add_response_handler を参照してください。

別のスレッドが Net::IMAP#idle_done を呼びだすまでこのメソッドを呼びだしたスレッドは停止します。

この命令は [RFC2177] で定義されています。詳しくはそちらを参照してください。

idle_done -> ()Ruby 1.9.3 から[permalink][rdoc][edit]

Net::IMAP#idle で停止しているスレッドを1つ起こします。

idle_response_timeout -> IntegerRuby 3.0 から[permalink][rdoc][edit]

IDLE の応答を待つ秒数を返します。

接続の設定 Net::IMAP::Config#idle_response_timeout の値を返します。

[SEE_ALSO] Net::IMAP#idle

list(refname, mailbox) -> [Net::IMAP::MailboxList] | nil[permalink][rdoc][edit]

LIST コマンドを送り、クライアントから利用可能なメールボックス名の集合から引数にマッチするものすべてを返します。

詳しくは [RFC2060] の 6.3.8 を参照してください。

返り値は Net::IMAP::MailboxList の配列で返します。返り値が空集合である場合は空の配列でなく nil を返します。

[PARAM] refname:: 参照名(文字列)
[PARAM] mailbox:: 調べるメールボックスの名前(文字列)。ワイルドカードを含んでいてもかまいません。

例

imap.create("foo/bar")
imap.create("foo/baz")
p imap.list("", "foo/%")
# => [#<Net::IMAP::MailboxList attr=[:Noselect], delim="/", name="foo/">, #<Net::IMAP::MailboxList attr=[:Noinferiors, :Marked], delim="/", name="foo/bar">, #<Net::IMAP::MailboxList attr=[:Noinferiors], delim="/", name="foo/baz">]

login(user, password) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

Net::IMAP#authenticate で "LOGIN" を使うのとは異なることに注意してください。authenticate では AUTHENTICATE コマンドを送ります。

認証成功時には認証成功レスポンスを返り値として返します。

認証失敗時には例外が発生します。

[PARAM] user:: ユーザ名文字列
[PARAM] password:: パスワード文字列
[EXCEPTION] Net::IMAP::NoResponseError:: 認証に失敗した場合に発生します
[EXCEPTION] Net::IMAP::LoginDisabledError:: サーバの機能一覧に LOGINDISABLED があり、Net::IMAP::Config#enforce_logindisabled の設定で確認する場合に発生します。LOGIN コマンドは送られません

[SEE_ALSO] Net::IMAP#authenticate

logout -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

LOGOUT コマンドを送り、コネクションを切断することをサーバに伝えます。

lsub(refname, mailbox) -> [Net::IMAP::MailboxList][permalink][rdoc][edit]

LIST コマンドを送り、active/subscribed なメールボックス名の集合から引数にマッチするものすべてを返します。

詳しくは [RFC2060] の 6.3.8 を参照してください。

返り値は Net::IMAP::MailboxList の配列で返します。返り値が空集合である場合は空の配列でなく nil を返します。

[PARAM] refname:: 参照名(文字列)
[PARAM] mailbox:: 調べるメールボックスの名前(文字列)。ワイルドカードを含んでいてもかまいません。

max_response_size -> Integer | nilRuby 4.0 から[permalink][rdoc][edit]

サーバの応答 1 つの大きさの上限(バイト数)を返します。

接続の設定 Net::IMAP::Config#max_response_size の値を返します。 nil は上限がないことを表します。

[SEE_ALSO] Net::IMAP#max_response_size=

max_response_size=(val)Ruby 4.0 から[permalink][rdoc][edit]

サーバの応答 1 つの大きさの上限(バイト数)を設定します。

接続の設定 Net::IMAP::Config#max_response_size= に設定します。

[PARAM] val:: 上限のバイト数。nil で上限をなくします。

[SEE_ALSO] Net::IMAP#max_response_size

move(set, mailbox) -> Net::IMAP::TaggedResponseRuby 2.3.0 から[permalink][rdoc][edit]

MOVEコマンドを送り、set で指定したメッセージを mailbox の末尾に移動させます。

set はmessage sequence number(整数)、 message sequence numberの配列、もしくは Range で指定します。

コピー元のメールボックスは Net::IMAP#examine もしくは Net::IMAP#select で指定したものを用います。

[PARAM] set:: 移動するメッセージの message sequence number(整数、整数の配列、整数の Range)
[PARAM] mailbox:: 移動先のメールボックス(文字列)

[SEE_ALSO] Net::IMAP#uid_move, [RFC6851]

noop -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

NOOP コマンドを送ります。

このコマンドは何もしません。

open_timeout -> IntegerRuby 3.0 から[permalink][rdoc][edit]

接続が確立するまで待つ秒数を返します。

接続の設定 Net::IMAP::Config#open_timeout の値を返します。

[SEE_ALSO] Net::IMAP.new

remove_response_handler(handler) -> ()[permalink][rdoc][edit]

レスポンスハンドラを削除します。

[PARAM] handler:: 削除するハンドラ

[SEE_ALSO] Net::IMAP#add_response_handler

rename(mailbox, newname) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

RENAME コマンドを送り、指定したメールボックスをリネームします。

[PARAM] mailbox:: リネームするメールボックス(文字列)
[PARAM] newname:: リネーム後の名前(文字列)
[EXCEPTION] Net::IMAP::NoResponseError:: 指定した名前のメールボックスをリネームできなかった場合に発生します。指定した名前のメールボックスが存在しない場合や、リネーム後の名前を持つメールボックスが既に存在する場合に発生します。

response_handlers -> Array[permalink][rdoc][edit]

設定されているレスポンスハンドラ全てを配列で返します。

[SEE_ALSO] Net::IMAP#add_response_handler

responses -> { String => [object] }[permalink][rdoc][edit]

responses(type) -> [object]

responses {|hash| ... } -> object

responses(type) {|array| ... } -> object

サーバから送られてきた untagged な応答の記録を返します。

untagged な応答は種類ごとに記録されます。応答の種類には "FLAGS", "OK", "UIDVALIDITY", "EXISTS" などがあり、この文字列がハッシュテーブルのキーとなります。そして各種類ごとに配列が用意され、untagged な応答を受信するたびにその配列の末尾にその内容が記録されます。

ブロックを渡すと、記録をブロックに渡してブロックの値を返します。 type を指定するとその種類の応答の配列だけを渡します(type は大文字に変換して探します)。ブロックの実行中は受信スレッドなどが記録を更新しないよう同期されます。ブロックの外で記録のハッシュやその配列を扱うのはスレッド安全ではないため、下の例のようにブロックを渡して使います。

ブロックを渡さないときは、type を指定するとその種類の応答の配列を凍結した複製を返します。 type を指定しないときの動作は接続の設定 Net::IMAP::Config#responses_without_block で決まり、既定値の :frozen_dup では記録のハッシュを凍結した複製(値の配列も凍結したもの)を返します。 :raise を設定すると ArgumentError が発生します。

例

imap.select("inbox")
p imap.responses("EXISTS", &:last)
# => 2
p imap.responses("UIDVALIDITY", &:last)
# => 968263756

[PARAM] type:: 応答の種類("EXISTS" など)を文字列で指定します。
[EXCEPTION] ArgumentError:: ブロックも type も渡さず、設定 responses_without_block が :raise の場合に発生します。

search(keys, charset = nil) -> [Integer][permalink][rdoc][edit]

SEARCH コマンドを送り、条件に合うメッセージの message sequence number を配列で返します。

Net::IMAP#examine もしくは Net::IMAP#select で指定したメールボックスを検索対象とします。

検索の条件は key に文字列の1次元配列もしくは文字列で渡します。

検索条件は "SUBJECT", "FROM" などを用いることができます。詳しくは [RFC2060] の 6.4.4 を見てください。

例

p imap.search(["SUBJECT", "hello"])
# => [1, 6, 7, 8]
p imap.search(["SUBJECT", "hello", "FROM", "foo@example.com"])
# => [6, 7]
p imap.search('SUBJECT "hello"')
# => [1, 6, 7, 8]

[PARAM] keys:: 検索キー(文字列の配列もしくは文字列)
[PARAM] charset:: 検索に用いるcharset

[SEE_ALSO] Net::IMAP#search

select(mailbox, condstore: false) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

SELECT コマンドを送り、指定したメールボックスを処理対象のメールボックスにします。

このコマンドが成功すると、クライアントの状態が「selected」になります。

このコマンドを実行した直後に Net::IMAP#responses["EXISTS"].last を調べると、メールボックス内のメールの数がわかります。また、Net::IMAP#responses["RECENT"].lastで、最新のメールの数がわかります。これらの値はセッション中に変わりうることに注意してください。 Net::IMAP#add_response_handler を使うとそのような更新情報を即座に取得できます。

[PARAM] mailbox:: 処理対象としたいメールボックスの名前(文字列)
[PARAM] condstore:: 真を指定すると CONDSTORE 拡張([RFC7162])を有効にします。メールボックスが mod-sequence の保持に対応していれば HIGHESTMODSEQ 応答コードが untagged な応答として送られ、以後の FETCH の応答に mod-sequence が含まれます。
[EXCEPTION] Net::IMAP::NoResponseError:: mailboxが存在しない等の理由でコマンドの実行に失敗した場合に発生します。

setacl(mailbox, user, rights)[permalink][rdoc][edit]

SETACL コマンドを送り、指定したメールボックスに指定したユーザに関する権限を設定します。

rights には設定する権限を表す文字列を指定します。どのような文字列を指定すべきかは [RFC2086] を参照してください。 rights に nil を渡すと、空文字列を指定したのと同様、つまりすべての権限を削除します。

[PARAM] mailbox:: 権限を設定するメールボックスの名前(文字列)
[PARAM] user:: 権限を設定するユーザの名前(文字列)
[PARAM] rights:: 権限を表す文字列

setquota(mailbox, quota) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

SETQUOTA コマンドを送り、指定したメールボックスに quota を設定します。

quota が nil ならば、mailbox の quota を破棄します。 quota が整数なら STORAGE をその値に変更します。

詳しくは [RFC2087] を見てください。このコマンドは Net::IMAP#capability の返り値を見ることで利用可能かどうか判断できます。

[PARAM] mailbox:: quota を設定するメールボックス名(文字列)
[PARAM] quota:: quotaの値(ストレージのサイズ、もしくは nil)
[EXCEPTION] Net::IMAP::NoResponseError:: 指定したメールボックスが quota root でない場合、もしくは権限が存在しない場合に発生します。

sort(sort_keys, search_keys, charset) -> [Integer][permalink][rdoc][edit]

uid_sort(sort_keys, search_keys, charset) -> [Integer]

SORT コマンド送り、メールボックス内のメッセージをソートした結果を返します。

SORT コマンドは [RFC5256] で定義されています。詳しくはそちらを参照してください。このコマンドは Net::IMAP#capability の返り値を見ることで利用可能かどうか判断できます。

sort_keys にはソート順を決めるキーを文字列の配列で指定します。 "ARRIVAL", "CC", "FROM", "TO", "SUBJECT" などが指定できます。詳しくは [RFC5265] の BASE.6.4.SORT の所を見てください。

search_key には検索条件を渡します。Net::IMAP#search とほぼ同じです。この条件にマッチするメッセージのみがソートされます。

Net::IMAP#examine もしくは Net::IMAP#select で指定したメールボックスを対象とします。

返り値は message sequence number の配列を返します。

例

p imap.sort(["FROM"], ["ALL"], "US-ASCII")
# => [1, 2, 3, 5, 6, 7, 8, 4, 9]
p imap.sort(["DATE"], ["SUBJECT", "hello"], "US-ASCII")
# => [6, 7, 8, 1]

[PARAM] sort_keys:: ソート順のキー(文字列配列)
[PARAM] search_keys:: 検索条件(文字列配列)
[PARAM] charset:: 検索条件の解釈に用いるCHARSET名(文字列)

starttls(**options) -> Net::IMAP::TaggedResponseRuby 1.9.3 から[permalink][rdoc][edit]

STARTTLS コマンドを送って TLS のセッションを開始します。

キーワード引数 options は OpenSSL::SSL::SSLContext#set_params にそのまま渡されます。キーは OpenSSL::SSL::SSLContext の属性の代入メソッドの名前です。 TLS の交渉とホスト名の検証が両方成功してから返ります。

サーバが TLS の開始に同意した後、接続の設定 Net::IMAP::Config#open_timeout の秒数まで待ち、それを超えると Net::OpenTimeout が発生します。

互換性のため、starttls(options)(options はハッシュ)と starttls(certs, verify) の形も受け付けます。 starttls(options) はハッシュをキーワード引数に変換します。 starttls(certs, verify) の形は非推奨で、警告を出します。 certs と verify は Net::IMAP.new の certs と verify と同じように変換します。この警告は Warning[:deprecated] が真のとき(-W:deprecated を指定したときなど)だけ表示されます。

[PARAM] options:: OpenSSL::SSL::SSLContext#set_params に渡す SSL/TLS のパラメータ
[EXCEPTION] ArgumentError:: 互換のための形の引数とキーワード引数を同時に渡した場合や、options のハッシュと verify を同時に渡した場合に発生します

status(mailbox, attr) -> {String => Integer}[permalink][rdoc][edit]

STATUS コマンドを送り、mailbox のステータスを得ます。

問い合わせたいステータスは attr に文字列の配列で渡します。

返り値はアトリビュート文字列をキーとするハッシュです。

詳しくは [RFC2060] の 6.3.10 を参考にしてください。

例

p imap.status("inbox", ["MESSAGES", "RECENT"])
# => {"RECENT" => 0, "MESSAGES" => 44}

[PARAM] mailbox:: 問い合わせ対象のメールボックス(文字列)
[PARAM] attr:: 問合せたいアトリビュート名(文字列)の配列
[EXCEPTION] Net::IMAP::NoResponseError:: メールボックスが存在しない場合や、アトリビュート名が存在しない場合に発生します

store(set, attr, flags, unchangedsince: nil) -> [Net::IMAP::FetchData] | nil[permalink][rdoc][edit]

STORE コマンドを送り、メールボックス内のメッセージを更新します。

set で更新するメッセージを指定します。これには sequence number、sequence number の配列、もしくは Range オブジェクトを渡します。

Net::IMAP#select で指定したメールボックスを対象とします。

attr で何をどのように変化させるかを指定します。以下を指定できます。

"FLAGS"
"+FLAGS"
"-FLAGS"

それぞれメッセージのフラグの置き換え、追加、削除を意味します。詳しくは [RFC2060] の 6.4.6 を参考にしてください。

flags にはシンボルの配列で置き換え、追加もしくは削除されるフラグを指定します。

返り値は更新された内容を Net::IMAP::FetchData オブジェクトの配列で返します。

例

p imap.store(6..8, "+FLAGS", [:Deleted])
# => [#<Net::IMAP::FetchData seqno=6, attr={"FLAGS" => [:Seen, :Deleted]}>, #<Net::IMAP::FetchData seqno=7, attr={"FLAGS" => [:Seen, :Deleted]}>, #<Net::IMAP::FetchData seqno=8, attr={"FLAGS" => [:Seen, :Deleted]}>]

[PARAM] set:: 更新するメッセージのsequence number
[PARAM] attr:: 更新方式(文字列)
[PARAM] flags:: 更新内容(Symbol の配列)
[PARAM] unchangedsince:: mod-sequence を整数で指定すると、mod-sequence がそれより大きいメッセージは更新しません。更新しなかったメッセージは MODIFIED 応答コードで返されます。指定すると CONDSTORE 拡張([RFC7162])を暗黙に有効にします。

[SEE_ALSO] Net::IMAP#uid_store, Net::IMAP#fetch

subscribe(mailbox) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

SUBSCRIBE コマンドを送り、指定したメールボックスを "active" もしくは "subscribe" なメールボックスの集合に追加します。

[PARAM] mailbox:: 追加するメールボックスの名前(文字列)
[EXCEPTION] Net::IMAP::NoResponseError:: 指定した名前のメールボックスを追加できなかった場合に発生します。指定した名前のメールボックスが存在しない場合などに生じます。

thread(algorithm, search_keys, charset) -> [Net::IMAP::ThreadMember][permalink][rdoc][edit]

THREADコマンドを送り、メールボックスを検索した結果をスレッド形式の木構造で返します。

THREAD コマンドは [RFC5256] で定義されています。詳しくはそちらを参照してください。このコマンドは Net::IMAP#capability の返り値を見ることで利用可能かどうか判断できます。

algorithm は木構造を決定するためのアルゴリズムを指定します。以下の2つが利用可能です。

"ORDEREDSUBJECT" subjectを使って平坦に区切るだけ
"REFERENCES" どのメッセージに返事をしているかを見て木構造を作る

詳しくは [RFC5256] を見てください。

search_key には検索条件を渡します。 Net::IMAP#search と同等です。

[PARAM] algorithm:: スレッド構造構築アルゴリズム名(文字列)
[PARAM] search_keys:: 検索条件(文字列配列)
[PARAM] charset:: 検索条件の解釈に用いるCHARSET名(文字列)

[SEE_ALSO] Net::IMAP::ThreadMember, Net::IMAP#uid_thread

uid_copy(set, mailbox) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

UID COPY コマンドを送り、指定したメッセージを指定したメールボックスの末尾に追加します。

set でコピーするメッセージを指定します。 UID (整数)、 UID の配列、もしくは Range で指定します。コピー元のメールボックスは Net::IMAP#examine もしくは Net::IMAP#select で指定したものを用います。 mailbox はコピー先のメールボックスです。

[PARAM] set:: コピーするメッセージの UID
[PARAM] mailbox:: コピー先のメールボックス(文字列)

[SEE_ALSO] Net::IMAP#copy

uid_fetch(set, attr, changedsince: nil, partial: nil) -> [Net::IMAP::FetchData][permalink][rdoc][edit]

UID FETCH コマンドを送り、メールボックス内のメッセージに関するデータを取得します。

Net::IMAP#examine もしくは Net::IMAP#select で指定したメールボックスを対象とします。

set で対象とするメッセージを指定します。これには UID、UID の配列、もしくは Range オブジェクトを渡します。 attr には取得するアトリビュートを文字列の配列で渡してください。指定可能なアトリビュートについては Net::IMAP::FetchData#attr を見てください。

[PARAM] set:: 処理対象のメッセージの UID
[PARAM] attr:: アトリビュート(文字列配列)
[PARAM] changedsince:: mod-sequence を整数で指定すると、mod-sequence がそれより大きいメッセージだけを対象にします。指定すると CONDSTORE 拡張([RFC7162])を暗黙に有効にします。
[PARAM] partial:: 返す結果の範囲を Range で指定し、件数を制限します。1..500 で set のうち最初の 500 件、-500..-1 で最後の 500 件です。サーバが PARTIAL 拡張([RFC9394])に対応している必要があります。

[SEE_ALSO] Net::IMAP#fetch

uid_move(set, mailbox) -> Net::IMAP::TaggedResponseRuby 2.3.0 から[permalink][rdoc][edit]

MOVEコマンドを送り、set でUIDで指定したメッセージを mailbox の末尾に移動させます。

set には UID、UID の配列、もしくは Range オブジェクトを渡します。

コピー元のメールボックスは Net::IMAP#examine もしくは Net::IMAP#select で指定したものを用います。

[PARAM] set:: 移動するメッセージのUID(整数、整数の配列、整数の Range)
[PARAM] mailbox:: 移動先のメールボックス(文字列)

[SEE_ALSO] Net::IMAP#move, [RFC6851]

uid_search(keys, charset = nil) -> [Integer][permalink][rdoc][edit]

UID SEARCH コマンドを送り、条件に合うメッセージの UID を配列で返します。

Net::IMAP#examine もしくは Net::IMAP#select で指定したメールボックスを検索対象とします。

検索の条件は key に文字列の1次元配列もしくは文字列で渡します。

検索条件は "SUBJECT", "FROM" などを用いることができます。詳しくは [RFC2060] の 6.4.4 を見てください。

例

p imap.uid_search(["SUBJECT", "hello"])
# => [1, 6, 7, 8]
p imap.uid_search(["SUBJECT", "hello", "FROM", "foo@example.com"])
# => [6, 7]
p imap.uid_search('SUBJECT "hello"')
# => [1, 6, 7, 8]

[PARAM] keys:: 検索キー(文字列の配列もしくは文字列)
[PARAM] charset:: 検索に用いるcharset

[SEE_ALSO] Net::IMAP#uid_search

uid_store(set, attr, flags, unchangedsince: nil) -> [Net::IMAP::FetchData] | nil[permalink][rdoc][edit]

UID STORE コマンドを送り、メールボックス内のメッセージを更新します。

set で更新するメッセージを指定します。これには UID、UID の配列、もしくは Range オブジェクトを渡します。

Net::IMAP#select で指定したメールボックスを対象とします。

attr で何をどのように変化させるかを指定します。以下を指定できます。

"FLAGS"
"+FLAGS"
"-FLAGS"

それぞれメッセージのフラグの置き換え、追加、削除を意味します。詳しくは [RFC2060] の 6.4.6 を参考にしてください。

返り値は更新された内容を Net::IMAP::FetchData オブジェクトの配列で返します。

[PARAM] set:: 更新するメッセージの UID
[PARAM] attr:: 更新方式(文字列)
[PARAM] flags:: 更新内容(Symbol の配列)
[PARAM] unchangedsince:: mod-sequence を整数で指定すると、mod-sequence がそれより大きいメッセージは更新しません。更新しなかったメッセージは MODIFIED 応答コードで返されます。指定すると CONDSTORE 拡張([RFC7162])を暗黙に有効にします。

[SEE_ALSO] Net::IMAP#store, Net::IMAP#uid_fetch

uid_thread(algorithm, search_keys, charset) -> [Net::IMAP::ThreadMember][permalink][rdoc][edit]

THREADコマンドを送り、メールボックスを検索した結果をスレッド形式の木構造で返します。

ほぼ Net::IMAP#thread と同じですが、返ってくるオブジェクトの Net::IMAP::ThreadMember#seqno の内容が message sequence number ではなく UID となります。

[PARAM] algorithm:: スレッド構造構築アルゴリズム名(文字列)
[PARAM] search_keys:: 検索条件(文字列配列)
[PARAM] charset:: 検索条件の解釈に用いるCHARSET名(文字列)

[SEE_ALSO] Net::IMAP::ThreadMember, Net::IMAP#thread

unsubscribe(mailbox) -> Net::IMAP::TaggedResponse[permalink][rdoc][edit]

UNSUBSCRIBE コマンドを送り、指定したメールボックスを "active" もしくは "subscribe" なメールボックスの集合から削除します。

[PARAM] mailbox:: 削除するするメールボックスの名前(文字列)
[EXCEPTION] Net::IMAP::NoResponseError:: 指定した名前のメールボックスを削除できなかった場合に発生します。指定した名前のメールボックスが active/subscribe でなかった場合などに発生します。

xlist(refname, mailbox) -> [Net::IMAP::MailboxList]Ruby 1.9.3 から[permalink][rdoc][edit]

XLISTコマンドを送り、クライアントから利用可能なメールボックス名の集合から引数にマッチするものすべてを返します。

Net::IMAP#list とほぼ同様ですが、「:Sent」などの拡張されたフラグを含むことが異なります。

詳しくは http://code.google.com/apis/gmail/imap/ を参照してください。

[PARAM] refname:: 参照名(文字列)
[PARAM] mailbox:: 調べるメールボックスの名前(文字列)。ワイルドカードを含んでいてもかまいません。

例

imap.create("foo/bar")
imap.create("foo/baz")
p imap.xlist("", "foo/%")
# => [#<Net::IMAP::MailboxList attr=[:Noselect], delim="/", name="foo/">, \\
#    #<Net::IMAP::MailboxList attr=[:Noinferiors, :Marked], delim="/", name="foo/bar">, \\
#    #<Net::IMAP::MailboxList attr=[:Noinferiors], delim="/", name="foo/baz">]

定数

ANSWERED -> Symbol[permalink][rdoc][edit]

「:Answered」というシンボルを返します。

そのメッセージに返答したことを意味します。

フラグメッセージ属性として用いられます (Net::IMAP::FetchData#attr)。

詳しくは [RFC2060] を参照してください。

DELETED -> Symbol[permalink][rdoc][edit]

「:Deleted」というシンボルを返します。

メッセージが削除されていることを意味します。 EXPUNGE で完全に除去されます。

フラグメッセージ属性として用いられます (Net::IMAP::FetchData#attr)。

詳しくは [RFC2060] を参照してください。

DRAFT -> Symbol[permalink][rdoc][edit]

「:Draft」というシンボルを返します。

メッセージが草稿であることを意味します。

フラグメッセージ属性として用いられます (Net::IMAP::FetchData#attr)。

詳しくは [RFC2060] を参照してください。

FLAGGED -> Symbol[permalink][rdoc][edit]

「:Flagged」というシンボルを返します。

そのメッセージに特別なフラグを立てていることを意味します。

フラグメッセージ属性として用いられます (Net::IMAP::FetchData#attr)。

詳しくは [RFC2060] を参照してください。

MARKED -> Symbol[permalink][rdoc][edit]

「:Marked」というシンボルを返します。

メールボックスが「interesting」であるとサーバによって印付けられていることを意味します。通常メールボックスに新しいメールが届いていることを意味します。

LIST応答の属性 (Net::IMAP#list、Net::IMAP::MailboxList#attr) として用いられます。

詳しくは [RFC2060] を参照してください。

NOINFERIORS -> Symbol[permalink][rdoc][edit]

「:Noinferiors」というシンボルを返します。

このメールボックスの下に子レベルの階層が存在不可能であることを意味します。

LIST応答の属性 (Net::IMAP#list、Net::IMAP::MailboxList#attr) として用いられます。

詳しくは [RFC2060] を参照してください。

NOSELECT -> Symbol[permalink][rdoc][edit]

「:Noselect」というシンボルを返します。

メールボックスが選択可能でないことを意味します。

LIST応答の属性 (Net::IMAP#list、Net::IMAP::MailboxList#attr) として用いられます。

詳しくは [RFC2060] を参照してください。

RECENT -> Symbol[permalink][rdoc][edit]

「:Recent」というシンボルを返します。

メッセージが「最近」メールボックスに到着したことを意味します。

フラグメッセージ属性として用いられます (Net::IMAP::FetchData#attr)。

詳しくは [RFC2060] を参照してください。

SEEN -> Symbol[permalink][rdoc][edit]

「:Seen」というシンボルを返します。

そのメッセージが既に読まれていることを意味します。

フラグメッセージ属性として用いられます (Net::IMAP::FetchData#attr)。

詳しくは [RFC2060] を参照してください。

UNMARKED -> Symbol[permalink][rdoc][edit]

「:Unmarked」というシンボルを返します。

メールボックスが印付けられていないことを意味します。メールボックスに新しいメールが届いていないことを意味します。

LIST応答の属性 (Net::IMAP#list、Net::IMAP::MailboxList#attr) として用いられます。

詳しくは [RFC2060] を参照してください。

要約

目次

特異メソッド

インスタンスメソッド

定数