Provided by: libnet-imap-perl_0.02-9_all 
NAME
Net::IMAP - A client interface to IMAP (Internet Message Access Protocol).
WARNING: This code is in alpha release. Expect the interface to change release to
release.
SYNOPSIS
"use Net::IMAP;"
DESCRIPTION
"Net::IMAP" provides a perl interface to the client portion of IMAP (Internet Message
Access Protocol).
add more meat - describe overall design (commands, responses, callbacks, convenience
routines
METHODS
new $host, %options
Creates a new "Net::IMAP" object, connects to $host on port 143, performs some preliminary
setup of the session, and returns a reference to the object.
Once connected, it processes the connection banner sent by the server. If the considers
the session to be preauthenticated, "new" notes the fact, allowing commands to be issued
without logging in.
The method also issues a "capability" command, and notes the result. If the server does
support IMAP4rev1, the method closes the connection and returns "undef".
The client will use non-synchronizing literals if the server supports the "LITERAL+"
extension (RFC2088) and the "NonSyncLits" options is set to 1.
The following "Net::xAP" options are relevant to "Net::IMAP":
"Synchronous => 1"
"NonSyncLits => 0"
"Debug => 0"
"InternetDraft => 0"
"Net::IMAP" also understands the following options, specific to the module:
"EOL => 'lf'"
Controls what style of end-of-line processing to presented to the end-programmer. The
default, 'lf', assumes that the programemr wants to fling messages terminated with
bare LFs when invoking append, and when fetching messages. In this case, the module
will map to/from CRLF accordingly.
If "EOL" is set to 'crlf', the assumption is that the programmer wants messages, or
portions of messages, to be terminated with CRLF. It also assumes the programmer is
providing messages terminated with the string when invoking the "append" method, and
will not provide an EOL mapping.
IMAP COMMAND METHODS
There are numerous commands in the IMAP protocol. Each of these are mapped to a
corresponding method in the "Net::IMAP" module.
Some commands can only be issued in certain protocol states. Some commands alter the
state of the session. These facts are indicated in the documentation for the individual
command methods.
The following list enumerates the protocol states:
Non-authenticated
The client has not authenticated with the server. Most commands are unavailable in
this state.
Authenticated
The client has authenticated with the server.
Selected
The client has opened a mailbox on the server.
noop
Sends a "noop" command to the server. It is valid in any protocol state.
This method is useful for placating the auto-logout god, or for triggering pending
unsolicited responses from the server.
capability
The "capability" method retrieves the capabilities the IMAP server supports. This method
is valid in any protocol state.
The server sends a "capability" response back to the client.
If the response does not indicate support for the "LITERAL+" extension, the "NonSyncLits"
option is forced off.
logout
Logs off of the server. This method is valid in any protocol state.
login $user, $password
Logs into the server using a simple plaintext password. This method is only valid when
the protocol is in the non-authenticated state.
If the server supports RFC2221 (IMAP4 Login Referrals), the completion response could
include a referral. See RFC2221 for further information about login referrals.
If successful, the session state is changed to authenticated.
authenticate $authtype, @authinfo
Logs into the server using the authentication mechanism specified in $authtype. This
method is only valid when the protocol is in the non-authenticated state.
The IMAP "authenticate" command is the same as that documented in RFC2222 (Simple
Authentication and Security Layer (SASL)), despite the fact that IMAP predates SASL.
If successful, the session state is changed to authenticated.
The following authentication mechanisms are currently supported:
'login'
This is a variation on the simple login technique, except that the information is
transmitted in Base64. This does not provide any additional security, but does allow
clients to use "authenticate".
'cram-md5'
This implements the authentication mechanism defined in RFC2195 (IMAP/POP AUTHorize
Extension for Simple Challenge/Response). It uses keyed MD5 to avoid sending the
password over the wire.
'anonymous'
This implements the authentication mechanism defined in RFC2245 (Anonymous SASL
Mechanism). Anonymous IMAP access is intended to provide access to public mailboxes
or newsgroups.
The method returns "undef" is $authtype specifies an unsupported mechanism or if the
server does not advertise support for the mechanism. The "has_authtype" method can be
used to see whether the server supports a particular authentication mechanism.
In general, if the server supports a mechanism supported by "Net::IMAP", the
"authenticate" command should be used instead of the "login" method.
select $mailbox
Opens the specified mailbox with the intention of performing reading and writing. This
method is valid only when the session is in the authenticated or selected states.
If successful, the server sends several responses: "flags", "exists", "resent", as well as
"ok" responses containing a "unseen", "permanentflags", "uidnext", and "uidvalidity"
codes. If also changes the session state to selected.
If server returns a "no" response containing a "newname" response code, this means
$mailbox does not exist but the server thinks this is because the folder was renamed. In
this case, try specifying the new folder name provided with the "newname" response code.
examine $mailbox
Opens the specified mailbox in read-only mode. This method is valid only when the session
is in the authenticated or selected states.
create $mailbox [, $partition]
Creates the specified mailbox. This method is valid only when the session is in the
authenticated or selected states.
The optional $partition argument is only valid with the Cyrus IMAP daemon. Refer to the
section 'Specifying Partitions with "create"' the "doc/overview" file for that package for
further information. This feature can only be used by administrators creating new
mailboxes. Other servers will probably reject the command if this argument is used. The
results are undefined if another server accepts a second argument.
delete $mailbox
Deletes the specified mailbox. Returns "undef" if $mailbox is the currently open mailbox.
This method is valid only when the session is in the authenticated or selected states.
rename $oldmailboxname, $newmailboxname [, $partition]
Renames the mailbox specified in $oldmailbox to the name specified in $newmailbox. This
method is valid only when the session is in the authenticated or selected states.
The optional $partition argument is only valid with the Cyrus IMAP daemon. Refer to the
section 'Specifying Partitions with "rename"' the "doc/overview" file for that package for
further information. This feature can only be used by administrators. Other servers will
probably reject the command if this argument is used. The results are undefined if
another server accepts a third argument.
subscribe $mailbox
Subscribe to the specified $mailbox. Subscribing in IMAP is subscribing in Usenet News,
except that the server maintains the subscription list. This method is valid only when
the session is in the authenticated or selected states.
unsubscribe $mailbox
Unsubscribe from the specified $mailbox. This method is valid only when the session is in
the authenticated or selected states.
list $referencename, $mailbox_pattern
Send an IMAP "list" command to the server. This method is valid only when the session is
in the authenticated or selected states.
Although IMAP folders do not need to be implemented as directories, think of an IMAP
reference name as a parameter given to a "cd" or "chdir" command, prior to checking for
folders matching $mailbox_pattern.
The $mailbox_pattern parameter allows a couple wildcard characters to list subsets of the
mailboxes on the server.
"*" Matches zero or more characters at the specified location.
"%" Like "*", matches zero or more characters at the specified location, but does not
match hierarchy delimiter characters.
If the last character in $mailbox_pattern is a "%", matching levels of hierarchy are
also returned. In other words: subfolders.
This method will fail, returning "undef", if $mailbox_pattern is "*". This behavior is
not built into the IMAP protocol; it is wired into "Net::IMAP". Doing otherwise could be
rude to both the client and server machines. If you want to know why, imagine doing
"list('#news.', '*')" on a machine with a full news feed. The "%" character should be
used to build up a folder tree incrementally.
If successful, the server sends a series of "list" responses.
Please note that the $referencename is an IMAPism, not a Perl reference. Also note that
the wildcards usable in $mailbox_pattern are specific to IMAP. Perl regexps are not
usable here.
lsub $referencename, $mailbox_pattern
Sends an IMAP "lsub" command to the server. The "lsub" command is similar to the "list"
command, except that the server only returns subscribed mailboxes. This method is valid
only when the session is in the authenticated or selected states.
The parameters are the same as those for the "list" method.
If successful, the server sends a series of "lsub" responses.
status $mailbox, @statusattrs
Retrieves status information for the specified $mailbox. This method is valid only when
the session is in the authenticated or selected states.
Per RFC2060, the @statusattrs can contain any of the following strings:
• messages
The number of messages in the mailbox.
• recent
The number of messages with the "\recent" flag set.
• uidnext
The UID expected to be assigned to the next mailbox appended to the mailbox. This
requires some explanation. Rather than using this value for prefetching the next UID,
it should be used to detect whether messages have been added to the mailbox. The
value will not change until messages are appended to the mailbox.
• uidvalidity
The unique identifier validity value of the mailbox.
• unseen
The number of messages without the "\seen" flag set.
This method will fail, returning "undef" if $mailbox is the currently open mailbox.
If successful, the server sends one or more "status" responses.
The status operation can be rather expensive on some folder implementations, so clients
should use this method sparingly.
append $mailbox, $message [, Flags => $flaglistref] [, Date => $date]
Appends the email message specified in $message to the mailbox specified in $mailbox.
This method is valid only when the session is in the authenticated or selected states.
In general, the email message should be a real RFC822 message, although exceptions such as
draft messages are reasonable in some situations. Also note that the line terminators in
$message need to be CRLF.
The "Flags" option allows a set of flags to be specified for the message when it is
appended. Servers are not required to honor this, but most, if not all, do so.
The "Date" option forces the internaldate to the specified value. If $date is a string,
the format of the string is "dd-mmm-yyyy hh:mm:ss [-+]zzzz", where "dd" is the day of the
month (starting from 1), "mmm" is the three-character abbreviation for the month name,
"yyyy" is the 4-digit year, "hh" is the hour, "mm" is the minutes, "ss" is the seconds,
and "[-+]zzzz" is the numeric timezone offset. This happens to be the same format
returned by the "internaldate" item from the "fetch" command. If $date is a list
reference, it is expected to contain two elements: a time integer and a timezone offset
string. The timezone string is expected to be formatted as "[-+]zzzz". These two values
will be used to synthesize a string in the format expected by the IMAP server. As with
the "Flags" options, servers are not required to honor the "Date" option, but most, if not
all, do so.
Note that the options are specified at the end of the list of method arguments. This is
due to the fact that it is possible to have a $mailbox named "Flags" or "Date".
Processing the options at the end of the argument list simplifies argument processing.
The order of the arguments will be changed if enough people complain.
If server returns a "no" response containing a "trycreate" response code, this means
$mailbox does not exist but the server thinks the command would have succeeded if the an
appropriate "create" command was issued. On the other hand, failure with no "trycreate"
response code generally means that a "create" should not be attempted.
check
Ask the server to perform a checkpoint of its data. This method is valid only when the
session is in the selected state.
While not always needed, this should be called if the client issues a large quantity of
updates to a folder in an extended session.
close
Close the current mailbox. This method is valid only when the session is in the selected
state.
If successful, the session state is changed to authenticated.
expunge
Delete messages marked for deletion. This method is valid only when the session is in the
selected state.
If successful, the server sends a series of "expunge" responses.
It will return "undef" is the mailbox is marked read-only.
search [Charset => $charset,] @searchkeys
Searches the mailbox for messages matching the criteria contained in @searchkeys. This
method is valid only when the session is in the selected state.
The @searchkeys list contains strings matching the format described in Section 6.4.4 of
RFC2060.
If successful, the server send zero or more "search" responses. Lack of a "search"
response means the server found no matches. Note that the server can send the results of
one search in multiple responses.
fetch $msgset, 'all'|'full'|'fast'|$fetchattr|@fetchattrs
Retrieves data about a set of messages. This method is valid only when the session is in
the selected state.
The $msgset parameter identifies the set of messages from which to retrieve the items of
interest. The notation accepted is similar to that found in ".newsrc" files, except that
":" is used to specify ranges, instead of "-". Thus, to specify messages 1, 2, 3, 5, 7,
8, 9, the following string could be used: '1:3,5,7:9'. The character "*" can be used to
indicate the highest message number in the mailbox. Thus, to specify the last 4 messages
in an 8-message mailbox, you can use '5-*'.
The following list enumerates the items that can be retrieved with "fetch". Refer to
Section 6.4.5 of RFC2060 for a description of each of these items.
• body[$section]<$partial>
• body.peek[$section]<$partial>
Important: the response item returned for a "body.peek" is "body".
• bodystructure
• body
• envelope
• flags
• internaldate
• rfc822
• rfc822.header
• rfc822.size
• rfc822.text
• uid
Please note that the items returning messages, or portion of messages, return strings
terminated with CRLF.
RFC2060 also defines several items that are actually macros for other sets of items:
• all
A macro equivalent to "('flags', 'internaldate', 'rfc822.size', 'envelope')".
• full
A macro equivalent to "('flags', 'rfc822.size', 'envelope', 'body')".
• fast
A macro equivalent to "('flags', 'internaldate', 'rfc822.size')".
The "all", "full", and "fast" items are not intended to be used with other items.
If successful, the server responses with one or more "fetch" responses.
If the completion response from a "fetch" command is "no", the client should send a "noop"
command, to force any pending expunge responses from the server, and retry the "fetch"
command with $msgset adjusted accordingly.
store $msgset, $itemname, @storeattrflags
Sets various attributes for the messages identified in $msgset. This method is valid only
when the session is in the selected state.
The $msgset parameter is described in the section describing "fetch".
The $itemname can be one of the following:
• flags
Replaces the current flags with the flags specified in @storeattrflags.
• +flags
Adds the flags specified in @storeattrflags to the current flags.
• -flags
Removes the flags specified in @storeattrflags from the current flags.
The $itemname can also have ".silent" appended, which causes the server to not send back
update responses for the messages.
If successful, and ".silent" is used used in $itemname, the server response with a series
of "fetch" responses reflecting the updates to the specified messages.
If the completion response from a "store" command is "no", the client should send a "noop"
command, to force any pending expunge responses from the server, and retry the "store"
command with $msgset adjusted accordingly.
The @storeattrflags is a list of flag strings.
copy $msgset, $mailbox
Copy the messages $msgset to the specified mailbox. This method is valid only when the
session is in the selected state.
The $msgset parameter is described in the section describing "fetch".
If server returns a "no" response containing a "trycreate" response code, this means
$mailbox does not exist but the server thinks the command would have succeeded if the an
appropriate "create" command was issued. On the other hand, failure with no "trycreate"
response code generally means that a "create" should not be attempted.
uid_copy $msgset, $mailbox
A variant of "copy" that uses UIDs in $msgset, instead of message numbers. This method is
valid only when the session is in the selected state.
uid_fetch $msgset, 'all'|'full'|'fast'|$fetchattr|@fetchattrs
A variant of "fetch" that uses UIDs, instead of message numbers, in $msgset and "fetch"
responses. This method is valid only when the session is in the selected state.
uid_search [Charset => $charset,] @searchkeys
A variant of "search" that uses UIDs, instead of message numbers, in $msgset and "search"
responses. This method is valid only when the session is in the selected state.
uid_store $msgset, $itemname, @storeattrflags
A variant of "store" that uses UIDs, instead of message numbers, in $msgset and "fetch"
responses. This method is valid only when the session is in the selected state.
CONVENIENCE ROUTINES
In addition to the core protocol methods, "Net::IMAP" provides several methods for
accessing various pieces of information.
is_preauth
Returns a boolean valud indicating whether the IMAP session is preauthenticated.
banner
Returns the banner string issued by the server at connect time.
capabilities
Returns the list of capabilities supported by the server, minus the authentication
capabilities. The list is not guaranteed to be in any specific order.
has_capability $capname
Returns a boolean value indicating whether the server supports the specified capability.
authtypes
Returns a list of authentication types supported by the server.
has_authtype $authname
Returns a boolean value indicating whether the server supports the specified
authentication type.
qty_messages
Returns the quantity of messages in the currently selected folder.
qty_recent
Returns the quantity of recent messages in the currently selected folder.
first_unseen
Returns the message number of the first unseen messages in the currently selected folder.
uidvalidity
Returns the "uidvalidity" value for the currently selected folder. This is useful for
IMAP clients that cache data in persistent storage. Cache data for a mailbox should only
be considered valid if the "uidvalidity" is the same for both cached data and the remote
mailbox. See Section 2.3.1.1 of RFC2060 for further details.
uidnext
Returns the "uidnext" value for the currently selected folder.
permanentflags
Returns the list of permanent flags the server has identified for the currently open
mailbox.
If a "\*" flag is present, the server allows new persistent keywords to be created.
is_permanentflag $flag
Returns a boolean value indicating whether the server considers $flag to be a permanent
flag.
flags
Returns a list of the flags associated with the mailbox.
has_flag $flag
Returns a boolean value indicating whether the given $flag is defined for the mailbox.
mailbox
Returns the name of the currently open mailbox. Returns "undef" if no mailbox is
currently open.
is_readonly
Returns a boolean value indicating whether the currently open mailbox is read-only.
NAMESPACE EXTENSION
The following methods are available if the server advertises support for RFC2342 (IMAP4
Namespace). Refer to that RFC for additional information.
namespace
Sends a "namespace" command to the server, if the server advertises support for the
extension extension.
ACCESS CONTROL EXTENSION
The following methods are available if the server advertises support for RFC2086 (IMAP4
ACL Extension). Refer to that RFC for additional information.
setacl $mailbox, $identifier, $modrights
Sets the access control list for $identifier on $mailbox according to the rights contained
in $modrights.
The $identifier typically identifies an account name, but can also specify abstract
entities, such as groups.
The format for $modrights is documented in RFC2086.
getacl $mailbox
Retrieves the access control list for $mailbox.
deleteacl $mailbox, $identifier
Deletes all access control list entries for $identifier from $mailbox.
listrights $mailbox, $identifier
List the rights available to $identifier for $mailbox.
myrights $mailbox
List the rights the current user has for $mailbox.
QUOTA EXTENSION
The following methods are available if the server advertises support for RFC2087 (IMAP4
Quota Extension). Refer to that RFC for additional information.
getquota $quotaroot
Lists the resource usage and limits for $quotaroot.
setquota $quotaroot, @setquotalist
Sets the resource limits for $quotaroot to @setquotalist.
Valid values for @setquotalist are server-dependant.
getquotaroot $mailbox
Lists the quota roots for $mailbox.
UIDPLUS EXTENSION
The following method is available if the server advertises support for RFC2359 (IMAP4
UIDPLUS Extension). Refer to that RFC for additional information.
uid_expunge $msgset
A variant of "expunge" that allows the operation to be narrowed to the messages with UIDs
specified in $msgset.
The $msgset parameter is described in the section describing "fetch".
CALLBACKS
Many of the command methods result in the server sending back response data. "Net::IMAP"
processes each response by parsing the data, packages it in an appropriate object, and
optionally calls a programmer-defined callback for the response. This callback mechanism
is how programmers get access to the data retrieved from the server.
set_untagged_callback $item, $coderef
Assigns a programmer-defined code reference to the associated untagged response. When an
untagged response matching $item is received, $coderef is called, with the IMAP object and
the associated response object passed as parameters.
The default callback for the "ok", "bye", "bad", and "no" untagged responses includes code
to output the text from "alert" responses to stderr, using "carp". If you set your own
callback for these responses, be sure to code handle "alert" codes. Per Section 7.1 of
RFC2060, clients are required to clearly display "alert" messages to users.
RESPONSE OBJECTS
As mention in the previous section, responses are parsed and packaged into response
objects, which are then passed to callbacks. Each type of response has a corresponding
object class. This section describes the various response objects provided.
All of the class names itemized below are prefixed with "Net::IMAP".
As a general rule, IMAP "nil" items are set to "undef" in the parsed data, and IMAP
parenthetical lists are converted to list references (of one form or another). In
addition, atoms, quoted strings, and literals are presented as Perl strings.
The condition responses ("ok", "no", "bad", "bye", and "preauth") can include a response
code. Refer to Section 7.1 in RFC2060 for a description of each of the standard response
codes.
Response
This is the object class for completion responses.
is_tagged
Returns a boolean value indicating whether the response is tagged. In the case of tagged
completion responses, this value is always 1.
has_trycreate
Returns a boolean value indicating whether the "TRYCREATE" response code is present in the
response. This can be used after a failed "append" or "copy" command to determine whether
the server thinks the operation would succeed if a "create" was issued for the associated
mailbox.
UntaggedResponse
This class is common to all untagged server responses.
tag
Returns a string containing the tag associated with the response. In the case of untagged
responses, this is always "*".
is_tagged
Returns a boolean value indicating whether the response is tagged. Obviously, in the case
of untagged responses, this value is always 0.
parent
Returns a reference to the parent IMAP object.
Ok
This is a container for untagged "ok" responses from the server.
code
Returns a list reference containing response code elements in the response. Returns
"undef" if no response code is present.
name
Returns the name of the response. In the case of "Ok", this returns 'ok'. This method is
provided as a convenience for end-programmers wanting to write one common subroutine for
one or more of the responses "Ok", "No", "Bad", and "Bye".
No
This is a container for untagged "no" responses from the server.
Bad
This is a container for untagged "bad" responses from the server.
Bye
This is a container for untagged "bye" responses from the server.
Expunge
This is a container for "expunge" responses from the server.
The information returned by "qty_messages" is automatically updated when "expunge"
responses are received.
msgnum
Returns the message number specified in the "expunge" response.
Capability
This is a container for "capability" responses.
capabilities
Returns the list of capabilities supported by the server, minus the authentication
capabilities. The list is not guaranteed to be in any specific order.
has_capability $capname
Returns a boolean value indicating whether the server supports the specified capability.
authtypes
Returns a list of authentication types supported by the server.
has_authtype $authname
Returns a boolean value indicating whether the server supports the specified
authentication type.
List
This is a container for "list" responses.
mailbox
Returns the name of the mailbox contained in the object.
delimiter
Returns the hierarchy delimiter associated with the mailbox.
flags
Returns a list of the flags associated with the mailbox.
has_flag $flag
Returns a boolean value indicating whether the given $flag is defined for the mailbox.
List
This is a container for "lsub" responses. It provides the same interface as the
"Net::IMAP::List" class.
Fetch
This is a container for "fetch" responses.
Responses for partial fetches bear special mention. While both the starting byte and
quantity of bytes are specified when doing partial fetches with the "fetch" command, the
corresponding response will only show the starting byte. In other words, the command
"$imap->fetch(1, 'body[]<0.1024>'" will, if successful, result in a fetch response item of
"body[]<0>" containing a 1024 octet value. To match a given response for a partial fetch,
you might need to use "length" to match it up with the corresponding item specified in the
"fetch" command.
msgnum
Returns the message number identified in the response.
items
Returns the list of data item names contained in the response. The list is not guaranteed
to be in any specific order.
item $item
Returns the data associated with the specified data item.
The following list enumerates the data types associated with each fetch item:
envelope Net::IMAP::Envelope
bodystructure Net::IMAP::BodyStructure
body Net::IMAP::BodyStructure
flags Net::IMAP::Flags
UID Integer
rfc822.size Integer
default String
Status
This is a container for "status" responses.
mailbox
Returns a string containing the mailbox the status information is associated with.
items
Returns the list of status items contains in the status response.
item $item
Returns the value of the $item status item.
Search
This is a container for "search" responses.
msgnums
Returns the list of message numbers contained in the response.
Flags
This is a container for "flags" responses.
flags
Returns the list of flags contained in the response.
has_flag $flag
Returns a boolean value indicating whether the specified flag is contained in the
response.
As a convenience, the information from the "flags" response is also stored in the parent
"Net::IMAP" object, and is available via "Net::IMAP" versions of the "flags" and
"has_flags" methods.
Exists
This is a container for "exists" responses.
exists
Returns the quantity of messages in the currently selected mailbox.
This is information is also available in the "qty_messages" method in the "Net::IMAP"
class.
Recent
This is a container for "recent" responses.
recent
Returns the number of messages with the "\recent" flag set.
This information is also available in the "qty_recent" method in the "Net::IMAP" class.
Namespace
This is a container for "namespace" responses.
personal [$namespace]
With no argument specified, returns a list of personal namespaces. If $namespace is
specified, returns the delimiter character for the specific personal namespace.
other_users [$namespace]
With no argument specified, returns a list of other users' namespaces. If $namespace is
specified, returns the delimiter character for the specific other users' namespace.
shared [$namespace]
With no argument specified, returns a list of shared namespaces. If $namespace is
specified, returns the delimiter character for the specific shared namespace.
ACL
This is a container for "acl" responses>
mailbox
Returns the name of the mailbox associated with the given ACL data.
identifiers
Returns a list of identifiers contained in the ACL data.
identifier $identifier
Listrights
This is a container for "listrights" responses.
mailbox
Returns the name of the mailbox associated with the given rights.
identifier
Returns a string containing the identifier associated with the rights.
rights
Returns a string containing the rights contained in the response.
Myrights
This is a container for "myrights" responses
mailbox
Returns the name of the mailbox associated with the given rights.
rights
Returns a string containing the rights contained in the response.
Quota
This is a container for "quota" responses.
quotaroot
Returns a string containing the name of the quota root in the response.
quotas
Returns a list of the quotas contained in the response.
usage $quota
Returns the usage value associated with the given $quota. Returns "undef" is the given
$quota is not present in the response.
limit $quota
Returns the usage limit associated with the given $quota. Returns "undef" is the given
$quota is not present in the response.
Quotaroot
This is a container for "quotaroot" responses.
mailbox
Returns the name of the mailbox associated with the quotaroot data.
quotaroots
If called in an array context, returns the list of quotaroots associated with the mailbox.
If called in a scalar context, returns a list reference.
MISC FETCH OBJECTS
A "fetch" response can be relatively complicated. This section documents various classes
and methods associated with the various pieces of information available in "fetch"
responses.
BodyStructure
This is a container for "bodystructure" items in "fetch" responses.
type
Returns a string containing the MIME type of the message. This is the left-hand portion
of a MIME media type. For example, the type of "text/plain" is "text".
subtype
Returns a string containing the MIME subtype of the message. This is the right-hand
portion of a MIME media type. For example, the subtype of "text/plain" is "plain".
parameters
Returns a reference to a hash containing the key/value attribute pairs in the
"Content-Type" field.
If, for example, the "Content-Type" field was:
Content-Type: text/plain; charset=us-ascii
The hash would contain one entry the a key of "charset", and a value of "us-ascii". The
key is always forced to be lowercase, but the case of the value is retained from the
server.
disposition
Returns the disposition type in the "Content-Disposition" field. Returns "undef" if no
such field exists.
disp_parameters
Returns a reference to a hash containing the key/value attributer pairs in the
"Content-Disposition" field. A reference to an empty hash is returned if no such field
exists, or if there are no parameters in the field.
language
Returns a reference to a list of the language tags present in the "Content-Language"
field. Returns a reference to an empty hash if no such field is present.
Multipart
This is a container for "BodyStructure" objects that are multipart entities.
parts
Returns a list reference of the body parts contained in the multipart entity.
Bodypart
This is a container for singlepart entities in "BodyStructure" and "Multipart" objects.
id
Return a string containing the contents of the "Content-ID" field, if one is present,
otherwise returns undef.
description
Return a string containing the contents of the "Content-Description" field, if one is
present, otherwise returns undef.
encoding
Returns a string containing the contents of the "Content-Transfer-Encoding" field.
Returns "undef" if no such field is in the entity.
size
Returns the number of octets in the entity.
lines
If the MIME content type is "message/rfc822" or the major type is "text", returns the
number of lines in the entity, else returns "undef".
envelope
If the MIME content type is "message/rfc822", returns a "Net::IMAP::Envelope" object,
otherwise returns undef.
bodystructure
If the MIME content type is "message/rfc822", returns a "Net::IMAP::BodyStructure" object,
otherwise returns undef.
md5
Returns a string containing the contents of the "Content-MD5" field. Returns "undef" if
no such field is in the entity.
Envelope
This is a container for envelope data in "fetch" responses.
For those familiar with SMTP, this is not the same type envelope. Rather, it is a
composite structure containing key source, destination, and reference information in the
message. When retrieved from the server, it is populated into a "Net::IMAP::Envelope"
object. The following methods are available.
date
Returns a string with the contents of the "Date" field.
subject
Returns a string with the contents of the "Subject" field.
from
Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "From"
field.
sender
Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "Sender"
field. If no "Sender" field is present in the message, the server will default it to the
contents of the "From" field.
reply_to
Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "Reply-To"
field. If no "Reply-To" field is present in the message, the server will default it to
the contents of the "From" field.
to
Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "To"field.
Will return "undef" if no "To" field exists in the message.
cc
Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "Cc" field.
Will return "undef" if no "Cc" field exists in the message.
bcc
Returns a list reference of "Net::IMAP::Addr" objects with the contents of the "Bcc"
field. Will return "undef" if no "Bcc" field exists in the message.
in_reply_to
Returns a string with the contents of the "In-Reply-To" field. Returns "undef" if no such
field is present in the message.
message_id
Returns a string with the contents of the "Date" field. Returns "undef" if no such field
is present in the message.
Addr
This is a container for address structures in "Envelope" objects.
phrase
Returns a string containing the phrase portion of the address, or "undef" if no phrase is
present.
route
Returns a string containing the route portion of the address, or "undef" if no route
information is present.
localpart
Returns a string containing the localpart portion of the address, or "undef" if no
localpart is present.
domain
Returns a string containing the domain portion of the address, or "undef" if no domain is
present.
as_string
Returns a string representation of the contents of the object.
CAVEATS
Minimal testing has been done against the various IMAP server implementations. Refer to
"BUGS" for known bugs/malfeatures.
AUTHOR
Kevin Johnson <kjj@pobox.com>
COPYRIGHT
Copyright (c) 1997-1999 Kevin Johnson <kjj@pobox.com>.
All rights reserved. This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.