Copyright (C) 2000 Shugo Maeda <shugo@ruby-lang.org>
This library is distributed under the terms of the Ruby license. You can freely distribute/modify this library.
Net::IMAP implements Internet Message Access Protocol (IMAP) clients. (The protocol is described in [IMAP].)
Net::IMAP supports multiple commands. For example,
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
This script invokes the FETCH command and the SEARCH command concurrently.
Object
Creates a new Net::IMAP object and connects it to the specified port on the named host. If usessl is true, then an attempt will be made to use SSL (now TLS) to connect to the server. For this to work OpenSSL[OSSL] and the Ruby OpenSSL[RSSL] extension need to be installed. The certs parameter indicates the path or file containing the CA cert of the server, and the verify parameter is for the OpenSSL verification callback.
Returns the debug mode.
Sets the debug mode.
Adds an authenticator for Net::IMAP#authenticate.
Returns an initial greeting response from the server.
Returns recorded untagged responses.
ex).
imap.select("inbox")
p imap.responses["EXISTS"][-1]
#=> 2
p imap.responses["UIDVALIDITY"][-1]
#=> 968263756
Disconnects from the server.
Sends a CAPABILITY command, and returns a listing of capabilities that the server supports.
Sends a NOOP command to the server. It does nothing.
Sends a LOGOUT command to inform the server that the client is done with the connection.
Sends an AUTEHNTICATE command to authenticate the client. The auth_type parameter is a string that represents the authentication mechanism to be used. Currently Net::IMAP supports "LOGIN" and "CRAM-MD5" for the auth_type.
ex).
imap.authenticate('LOGIN', user, password)
Sends a LOGIN command to identify the client and carries the plaintext password authenticating this user.
Sends a SELECT command to select a mailbox so that messages in the mailbox can be accessed.
Sends a EXAMINE command to select a mailbox so that messages in the mailbox can be accessed. However, the selected mailbox is identified as read-only.
Sends a CREATE command to create a new mailbox.
Sends a DELETE command to remove the mailbox.
Sends a RENAME command to change the name of the mailbox to the newname.
Sends a SUBSCRIBE command to add the specified mailbox name to the server's set of "active" or "subscribed" mailboxes.
Sends a UNSUBSCRIBE command to remove the specified mailbox name from the server's set of "active" or "subscribed" mailboxes.
Sends a LIST command, and returns a subset of names from the complete set of all names available to the client. The return value is an array of Net::IMAP::MailboxList.
ex).
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">]
Sends a LSUB command, and returns a subset of names from the set of names that the user has declared as being "active" or "subscribed". The return value is an array of Net::IMAP::MailboxList.
Sends a STATUS command, and returns the status of the indicated mailbox. The return value is a hash of attributes.
ex).
p imap.status("inbox", ["MESSAGES", "RECENT"])
#=> {"RECENT"=>0, "MESSAGES"=>44}
Sends a APPEND command to append the message to the end of the mailbox.
ex).
imap.append("inbox", <<EOF.gsub(/\n/, "\r\n"), [:Seen], Time.now)
Subject: hello
From: shugo@ruby-lang.org
To: shugo@ruby-lang.org
hello world
EOF
Sends a CHECK command to request a checkpoint of the currently selected mailbox.
Sends a CLOSE command to close the currently selected mailbox. The CLOSE command permanently removes from the mailbox all messages that have the \Deleted flag set.
Sends a EXPUNGE command to permanently remove from the currently selected mailbox all messages that have the \Deleted flag set.
Sends a SEARCH command to search the mailbox for messages that match the given searching criteria, and returns message sequence numbers (search) or unique identifiers (uid_search).
ex).
p imap.search(["SUBJECT", "hello"])
#=> [1, 6, 7, 8]
p imap.search('SUBJECT "hello"')
#=> [1, 6, 7, 8]
Sends a FETCH command to retrieve data associated with a message in the mailbox. the set parameter is a number or an array of numbers or a Range object. the number is a message sequence number (fetch) or a unique identifier (uid_fetch). The return value is an array of Net::IMAP::FetchData.
ex).
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
Sends a STORE command to alter data associated with a message in the mailbox. the set parameter is a number or an array of numbers or a Range object. the number is a message sequence number (store) or a unique identifier (uid_store). The return value is an array of Net::IMAP::FetchData.
ex).
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]}>]
Sends a COPY command to copy the specified message(s) to the end of the specified destination mailbox. the set parameter is a number or an array of numbers or a Range object. the number is a message sequence number (copy) or a unique identifier (uid_copy).
Sends a SORT command to sort messages in the mailbox.
ex).
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]
Sends a SETQUOTA command along with the specified mailbox and quota. If quota is nil, then quota will be unset for that mailbox. Typically one needs to be logged in as server admin for this to work. The IMAP quota commands are described in [RFC-2087].
Sends the GETQUOTA command along with specified mailbox. If this mailbox exists, then an array containing a Net::IMAP::MailboxQuota object is returned. This command generally is only available to server admin.
Sends the GETQUOTAROOT command along with specified mailbox. This command is generally available to both admin and user. If mailbox exists, returns an array containing objects of Net::IMAP::MailboxQuotaRoot and Net::IMAP::MailboxQuota.
Sends the SETACL command along with mailbox, user and the rights that user is to have on that mailbox. If rights is nil, then that user will be stripped of any rights to that mailbox. The IMAP ACL commands are described in [RFC-2086].
Send the GETACL command along with specified mailbox. If this mailbox exists, an array containing objects of Net::IMAP::MailboxACLItem will be returned.
Adds a response handler.
ex).
imap.add_response_handler do |resp| p resp end
Removes the response handler.
Returns all response handlers.
Net::IMAP::ContinuationRequest represents command continuation requests.
The command continuation request response is indicated by a "+" token instead of a tag. This form of response indicates that the server is ready to accept the continuation of a command from the client. The remainder of this response is a line of text.
continue_req ::= "+" SPACE (resp_text / base64)
Struct
Net::IMAP::UntaggedResponse represents untagged responses.
Data transmitted by the server to the client and status responses that do not indicate command completion are prefixed with the token "*", and are called untagged responses.
response_data ::= "*" SPACE (resp_cond_state / resp_cond_bye /
mailbox_data / message_data / capability_data)
Struct
Returns the name such as "FLAGS", "LIST", "FETCH"....
Returns the data such as an array of flag symbols, a Net::IMAP::MailboxList object....
Returns the raw data string.
Net::IMAP::TaggedResponse represents tagged responses.
The server completion result response indicates the success or failure of the operation. It is tagged with the same tag as the client command which began the operation.
response_tagged ::= tag SPACE resp_cond_state CRLF
tag ::= 1*<any ATOM_CHAR except "+">
resp_cond_state ::= ("OK" / "NO" / "BAD") SPACE resp_text
Struct
Returns the tag.
Returns the name. the name is one of "OK", "NO", "BAD".
Returns the data. See Net::IMAP::ResponseText.
Returns the raw data string.
Net::IMAP::ResponseText represents texts of responses. The text may be prefixed by the response code.
resp_text ::= ["[" resp_text_code "]" SPACE] (text_mime2 / text)
;; text SHOULD NOT begin with "[" or "="
Struct
Returns the response code. See Net::IMAP::ResponseCode.
Returns the text.
Net::IMAP::ResponseCode represents response codes.
resp_text_code ::= "ALERT" / "PARSE" /
"PERMANENTFLAGS" SPACE "(" #(flag / "\*") ")" /
"READ-ONLY" / "READ-WRITE" / "TRYCREATE" /
"UIDVALIDITY" SPACE nz_number /
"UNSEEN" SPACE nz_number /
atom [SPACE 1*<any TEXT_CHAR except "]">]
Struct
Returns the name such as "ALERT", "PERMANENTFLAGS", "UIDVALIDITY"....
Returns the data if it exists.
Net::IMAP::MailboxList represents contents of the LIST response.
mailbox_list ::= "(" #("\Marked" / "\Noinferiors" /
"\Noselect" / "\Unmarked" / flag_extension) ")"
SPACE (<"> QUOTED_CHAR <"> / nil) SPACE mailbox
Struct
Returns the name attributes. Each name attribute is a symbol capitalized by String#capitalize, such as :Noselect (not :NoSelect).
Returns the hierarchy delimiter
Returns the mailbox name.
Net::IMAP::MailboxQuota represents contents of GETQUOTA response. This object can also be a response to GETQUOTAROOT. In the syntax specification below, the delimiter used with the "#" construct is a single space (SPACE).
quota_list ::= "(" #quota_resource ")"
quota_resource ::= atom SPACE number SPACE number
quota_response ::= "QUOTA" SPACE astring SPACE quota_list
Struct
The mailbox with the associated quota.
Current storage usage of mailbox.
Quota limit imposed on mailbox.
Net::IMAP::MailboxQuotaRoot represents part of the GETQUOTAROOT response. (GETQUOTAROOT can also return Net::IMAP::MailboxQuota.)
quotaroot_response
::= "QUOTAROOT" SPACE astring *(SPACE astring)
Struct
The mailbox with the associated quota.
Zero or more quotaroots that effect the quota on the specified mailbox.
Net::IMAP::MailboxACLItem represents response from GETACL.
acl_data ::= "ACL" SPACE mailbox *(SPACE identifier SPACE
rights)
identifier ::= astring
rights ::= astring
Struct
Login name that has certain rights to the mailbox that was specified with the getacl command.
The access rights the indicated user has to the mailbox.
Net::IMAP::StatusData represents contents of the STATUS response.
Object
Returns the mailbox name.
Returns a hash. Each key is one of "MESSAGES", "RECENT", "UIDNEXT", "UIDVALIDITY", "UNSEEN". Each value is a number.
Net::IMAP::FetchData represents contents of the FETCH response.
Object
Returns the message sequence number. (Note: not the unique identifier, even for the UID command response.)
Returns a hash. Each key is a data item name, and each value is its value.
The current data items are:
A form of BODYSTRUCTURE without extension data.
A string expressing the body contents of the specified section.
An object that describes the [MIME-IMB] body structure of a message. See Net::IMAP::BodyTypeBasic, Net::IMAP::BodyTypeText, Net::IMAP::BodyTypeMessage, Net::IMAP::BodyTypeMultipart.
A Net::IMAP::Envelope object that describes the envelope structure of a message.
A array of flag symbols that are set for this message. flag symbols are capitalized by String#capitalize.
A string representing the internal date of the message.
Equivalent to BODY[].
Equivalent to BODY.PEEK[HEADER].
A number expressing the [RFC-822] size of the message.
Equivalent to BODY[TEXT].
A number expressing the unique identifier of the message.
Net::IMAP::Envelope represents envelope structures of messages.
Struct
Retunns a string that represents the date.
Retunns a string that represents the subject.
Retunns an array of Net::IMAP::Address that represents the from.
Retunns an array of Net::IMAP::Address that represents the sender.
Retunns an array of Net::IMAP::Address that represents the reply-to.
Retunns an array of Net::IMAP::Address that represents the to.
Retunns an array of Net::IMAP::Address that represents the cc.
Retunns an array of Net::IMAP::Address that represents the bcc.
Retunns a string that represents the in-reply-to.
Retunns a string that represents the message-id.
Net::IMAP::Address represents electronic mail addresses.
Struct
Returns the phrase from [RFC-822] mailbox.
Returns the route from [RFC-822] route-addr.
nil indicates end of [RFC-822] group. If non-nil and host is nil, returns [RFC-822] group name. Otherwise, returns [RFC-822] local-part
nil indicates [RFC-822] group syntax. Otherwise, returns [RFC-822] domain name.
Net::IMAP::ContentDisposition represents Content-Disposition fields.
Struct
Returns the disposition type.
Returns a hash that represents parameters of the Content-Disposition field.
Net::IMAP::BodyTypeBasic represents basic body structures of messages.
Struct
Returns the content media type name as defined in [MIME-IMB].
Returns the content subtype name as defined in [MIME-IMB].
Returns a hash that represents parameters as defined in [MIME-IMB].
Returns a string giving the content id as defined in [MIME-IMB].
Returns a string giving the content description as defined in [MIME-IMB].
Returns a string giving the content transfer encoding as defined in [MIME-IMB].
Returns a number giving the size of the body in octets.
Returns a string giving the body MD5 value as defined in [MD5].
Returns a Net::IMAP::ContentDisposition object giving the content disposition.
Returns a string or an array of strings giving the body language value as defined in [LANGUAGE-TAGS].
Returns extension data.
Returns false.
Net::IMAP::BodyTypeText represents TEXT body structures of messages.
Struct
Returns the size of the body in text lines.
And Net::IMAP::BodyTypeText has all methods of Net::IMAP::BodyTypeBasic.
Net::IMAP::BodyTypeMessage represents MESSAGE/RFC822 body structures of messages.
Struct
Returns a Net::IMAP::Envelope giving the envelope structure.
Returns an object giving the body structure.
And Net::IMAP::BodyTypeMessage has all methods of Net::IMAP::BodyTypeText.
Struct
Returns the content media type name as defined in [MIME-IMB].
Returns the content subtype name as defined in [MIME-IMB].
Returns multiple parts.
Returns a hash that represents parameters as defined in [MIME-IMB].
Returns a Net::IMAP::ContentDisposition object giving the content disposition.
Returns a string or an array of strings giving the body language value as defined in [LANGUAGE-TAGS].
Returns extension data.
Returns true.
M. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 2060, December 1996.
Alvestrand, H., "Tags for the Identification of Languages", RFC 1766, March 1995.
Myers, J., and M. Rose, "The Content-MD5 Header Field", RFC 1864, October 1995.
Freed, N., and N. Borenstein, "MIME (Multipurpose Internet Mail Extensions) Part One: Format of Internet Message Bodies", RFC 2045, November 1996.
Crocker, D., "Standard for the Format of ARPA Internet Text Messages", STD 11, RFC 822, University of Delaware, August 1982.
Myers, J., "IMAP4 QUOTA extension", RFC 2087, January 1997.
Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997.
http://www.openssl.org
http://savannah.gnu.org/projects/rubypki