new($server)

Creates a new IMAP object. You can optionally specify the server to connect to, using default parameters (see connect() for details). On success, an IMAP object reference is returned - on failure, a string is returned detailing the error.

debuglevel($level)

Set the debug level. Debug levels are set on a bitmask, and all debug output is to STDERR. Valid bits are as follows:

0x01 - Communications dump

0x02 - Fetch-parsing dump

onfail($action)

Tell the object what to do when a command fails, either in the object, or if a !OK response is received (i.e. NO or BAD). Valid values are 'ERROR' (return undef, set error()) or 'ABORT' (abort, printing error to stderr). Default is ERROR. Values are case insensitive.

errorstyle($action)

Controls how errors are handled when onfail is 'ERROR'. Valid values are 'LAST', for only storing the last error, or 'STACK', where all errors are saved until the next call to error(). STACK is most useful for those programs that tend to call nested functions, and finding where a program is truly failed (so the last error doesn't erase the original error that caused the problem). Default is 'STACK'

error()

Prints the last error encountered by the imap object. If you executed a command and received an undef in response, this is where the error description can be found.

capability_checking()

Enable or disable capability checking for those commands that support it. If enabled, a supported command will first check to see that the appropriate atom, as specified in the command's respective RFC, appears in the capability string. If it does not, the command will not be sent to the server, but immediately fail. If disabled, all commands will assume any required atom exists, and the command will be sent to the server.

Any valid 'true' value will enable the checking, while any 'false' value will disable it.

_imap_command($command, $arguments, <$continuation, ...)>

Execute an IMAP command, wait for and return the response. The function accepts the command as the first argument, arguments to that command as the second argument, followed by continuation responses for if/when the server issues a '+' response, such as '+ go ahead'. If there are less continuations specified than the server requests, the command will fail in the normal manner. If there are more continuations specified than the server requests, a warning is printed, however the response is parsed as usual - if it was OK then the command will be considered successful.

The function returns the server response on success, and undef on failure, setting error().

connect(%args)

Connect to the supplied IMAP server. Inerits all the options of IO::Socket::SSL (and thusly, IO::Socket::INET), and adds the following custom options:

ConnectMethod

IMAPSPort

IMAPPort

The error logs are cleared during a connection attempt, since (re)connecting essentially is a new session, and any previous errors cannot have any relation the current operation. Also, the act of finding the proper method of connecting can generate internal errors that are of no concern (as long as it ultimately connects). Should the connection fail, the error() log will contain the appropriate errors generated while attempting to connect. Should the connection succeed, the error log will be clear.

Returns 1 on success, and undef on failure, setting error().

disconnect()

Disconnect from the server. This command can safely be used on an already-disconnected server.

register_mailbox_update(&subfunction)

This function sets up a callback function for when the IMAP server sends back a Server Response in accordance with RFC3501 Section 7.3, which stiuplates that while select()ed or examine()ing a mailbox, updates as to the mailbox content can be sent back after any command as tagless responses.

The subfunction will be passed one hash argument. The hash argument will contain keys that represent the data type (EXISTS, RECENT), and their respective values will be the values returned by the server.

If no function is registered via this method, or this method is called with an 'undef' argument, no special action will be taken should these server responses be encountered by the library.

Request a listing of capabilities that the server supports. Note that the object caches the response of the capability() command for determining support of certain features.

noop()

Issue a "No Operation" command - i.e. do nothing. Also used for idling and checking for state changes in the select()ed mailbox

logout()

Log the current user out and return This function will not work for multi-stage commands, such as those that issue a '+ go ahead' to indicate the continuation to send data.the connection to the unauthorized state.

starttls(%args)

Issue a STARTTLS negotiation to secure the data connection. This function will call capability() twice - once before issuing the starttls() command to verify that the atom STARTTLS is listed as a capability(), and once after the sucessful negotiation, per RFC 3501 6.2.1. See capability() for unique rules on how this module handles capability() requests. Upon successful completion, the connection will be secured. Note that STARTTLS is not available if the connection is already secure (preivous sucessful starttls(), or connect() via SSL, for example).

STARTTLS is checked in capability() regardless of the value of capability_checking().

Any call arguments in %args are passed onto the underlying IO::Socket::SSL->start_SSL() function.

This function returns 1 on success, since there is no output to return on success. Failures are treated normally.

authenticate($login, $password)

authenticate($login, $password, $authorize_as)

authenticate2($login, $password)

authenticate2($login, $password, $authorize_as)

Login in using the AUTHENTICATE mechanism. This mechanism supports authorization as someone other than the logged in user, if said user has permission to do so. authenticate() uses a one-line login sequence, while authenticate2() uses a multi-line login sequence. Both are provided for compatiblity reasons.

OBSOLETE WARNING: In the future, this split-line behavior will be controlled by an object function, and authenticate() will be the only function.

login($username,$password)

Login using the basic LOGIN mechanism. Passwords are sent in the clear, and there is no third-party authorization support.

select($mailbox)

Open a mailbox in read-write mode so that messages in the mailbox can be accessed. This function returns a hash of the valid tagless responses. According to RFC-3501, these responses include:

• FLAGS (<flags>)
• <n> EXISTS
• <n> RECENT
• OK [UNSEEN <n>]
• OK [PERMANENTFLAGS <flaglist>]
• OK [UIDNEXT <n>]

If the server supports an earlier version of the protocol than IMAPv4, the only flags required are FLAGS, EXISTS, and RECENT.

Finally, hash responses will have an 'OK' key that will contain the current permissional status, either 'READ-WRITE' or 'READ-ONLY', if returned by the server. Returns an empty (undefined) hash on error.

IMPORTANT! You should always check to see if an ALERT was issued. ALERTs should be relayed to the user if they exist!

examine($mailbox)

Identical to select(), except the mailbox is opened READ-ONLY. Returns an empty (unefined) hash on error.

create($mailbox,\%properties)

Create a mailbox with the given name. Also assigns the properties given immediately upon creation. Valid properties are:

• quota - A hash, with the keys being the type (aka STORAGE), and the values being the actual quota for that type, with size-based quotas given in kb
• permissions - initial permissions for the mailbox owner(s) (equivalent to setacl), for if the owner needs different permissions than the server's default

For example: $imap->create("asdfasdf",{quota=>{'STORAGE',50000}, permissions => 'lrws'})

delete($mailbox)

Delete an existing mailbox with the given name. NOTE: RFC notes that sub-mailboxes are not automatically deleted via this command.

rename($oldmailbox,$newmailbox)

Rename an existing mailbox from oldmailbox to newmailbox.

subscribe($mailbox)

Subscribe the authorized user to the given mailbox

unsubscribe($mailbox)

Unsubscribe the authorized user from the given mailbox

list($reference,$mailbox)

List all the local mailboxes the authorized user can see for the given mailbox from the given reference. Returns a listref of hashrefs, with each list entry being one result. Keys in the hashes include FLAGS, REFERENCE, and MAILBOX, and their returned values, respectivly.

lsub($reference,$mailbox)

List all the local subscriptions for the authorized user for the given mailbox from the given reference. Returns a listref of hashrefs, which each list entry being one result. Keys in the hashes include FLAGS, REFERENCE, and MAILBOX, and their returned values, respectivly.

status($mailbox,@status)

Get the provided status items on the currently select()ed or examine()d mailbox. Each argument is a different status information item to query. According to RFC, the following tags are valid for status() queries: MESSAGES, RECENT, UIDNEXT, UIDVALIDITY, UNSEEN. Since there may be future RFC declarations or custom tags for various servers, this module does not restrict to the above tags, but rather lets the server handle them appropriately (which may be a NO or BAD response).

Upon successful completion, the return value will be a hash of the queried items and their returned values.

append($mailbox, $message, $flaglist)

Append the given message to the given mailbox with the given flaglist. For information on the flaglist, see the buildflaglist() method.

The append() method will do some housekeeping on any message that comes in - namely, it will ensure that all lines end in 'CRLF'. The reasoning is that the RFC strictly states that lines must end in 'CRLF', and most *nix files end with just 'LF' - therefore rather than force every program to muck with message inputs to ensure compatiblity, the append() method will ensure it for them.

This 'CRLF' assurance is done for all commands - however its noted here because it also does it to the message itself in this method, potentially modifying data.

Unless overridden, append will check for the LITERAL+ capability() atom, and use non-synchronizing literals if supported - otherwise, it will use the standard IMAP dialog.

Upon successful execution, the return of this function depends on the type of variable receiving the data.

check()

Request a checkpoint of the currently select()ed mailbox. The specific actions and responses by the server are on an implementation-dependant basis.

close()

Close the currently select()ed mailbox, expunge()ing any messages marked as \Deleted first. Unlike expunge(), this command does not return any untagged responses, and closes the mailbox upon completion.

expunge()

Expunge() any messages marked as \Deleted from the currently select()ed mailbox. Will return untagged responses indicating which messages have been expunge()d.

search($searchstring,<$charset)>

Search for messages in the currently select()ed or examine()d mailbox matching the searchstring critera, where searchstring is a valid IMAP search query.See the end of this document for valid search terminology. The charset argument is optional - undef defaults to ASCII.

This function returns a listref of sequence IDs that match the query when in list context, and a space-seperated list of sequence IDs if in scalar context. The scalar context allows nested calling within functions that require sequences, such as `fetch(search('RECENT'),undef,'FLAGS')`

fetch($sequence, [\%body, \%body, ...], @other)

Fetch message data. The first argument is a sequence set to retrieve.

The second argument, the body hash ref, is designed to easily create the body section of the query, and takes the following arguments:

• body

  Specify the section of the body to fetch(). undef is allowed, meaning no arguments to the BODY option, which will request the full message (unless a header is specified - see below).

• offset

  Specify where in the body to start retrieving data, in octets. Default is from the beginning (0). If the offset is beyond the end of the data, an empty string will be returned. Must be specified with the length option.

• length

  Specify how much data to retrieve starting from the offset, in octets. If the acutal data is less than the length specified, the acutal data will be returned. There is no default value, and thus must be specified if offset is used.

• header

  Takes either 'ALL', 'MATCH', or 'NOT'. 'ALL' will return all the headers, regardless of the contents of headerfields. 'MATCH' will only return those headers that match one of the terms in headerfields, while 'NOT' will return only those headers that *do not* match any of the terms in the headerfields.

• headerfields

  Used when header is 'MATCH' or 'NOT', it specifies the headers to use for comparison. This argument is a string of space-seperated terms.

• peek

  When set to 1, uses the BODY.PEEK command instead of BODY, which preserves the \Seen state of the message

A single hash reference may be supplied for a single body command. If multiple body commands are required, they must be passed inside an array reference (i.e. [\%hash, \%hash]).

If an empty hashref is supplied as a \%body argument, it is interpreted as a BODY[] request.

The third argument, other, is a string of space-seperated stand-alone data items. Valid items via RFC3501 include:

• BODY

  The non-extensible form of BODYSTRUCTURE (not to be confused with the first argument - this command fetches structure, not content)

• BODYSTRUCTURE

  The MIME-IMB body structure of the message.

• ENVELOPE

  The RFC-2822 envelope structure of the message.

• FLAGS

  The flags set for the message

• INTERNALDATE

  The internal date of the message

• RFC822, RFC822.HEADER, RFC822.SIZE, RFC822.TEXT

  RFC822, RFC822.HEADER, and RFC822.TEXT are equivilant to the similarly-named BODY options from the first argument, except for the format they return the results in (in this case, RFC-822). Except RFC822.HEADER, which is the RFC822 equivilant of BODY.PEEK[HEADER], there is no '.PEEK' alternative available, so the \Seen state may be altered. SIZE returns the RFC-822 size of the message and does not change the \Seen state.

• UID

  The unique identifier for the message.

• ALL

  equivalent to FLAGS, INTERNALDATE, RFC822(SIZE), ENVELOPE

• FAST

  equivalent to FLAGS, INTERNALDATE RFC822(SIZE)

• FULL

  equivalent to FLAGS, INTERNALDATE, RFC822(SIZE), ENVELOPE, BODY()

The final argument, other, provides some basic option-sanity checking and assures that the options supplied are in the proper format.

The return value is a hash of nested hashes. The first level of hashes represents the message id. The second and subsequent levels represents a level of multiparts, equivilant to the depth computed by the server and used for the body[] section retrievals. Particularly subject to nested hashing are the BODY and BODYSTRUCTURE commands. Commands used in the other argument typically are found on the base level of the hash: for example, UID and FLAGS would be found on the first level. Structure and BODY parts are found nested in their appropriate sections.

This is a complex method for a data-rich command. Here are some examples to aid in your understanding:

This command is equivilant to `xxx FETCH 1 (BODY[1] BODY.PEEK[HEADER.FIELDS (FROM SUBJECT TO DATE X-STATUS) RFC822.SIZE FLAGS]`: $imap->fetch(1,[{header=>'MATCH', headerfields=>'FROM SUBJECT TO DATE X-STATUS ', peek=>1}, {body=>1, offset=>1024, length=>4000}], qw(RFC822.SIZE FLAGS));

Please see the "Fetch Response Tutorial" at the bottom of this document.

store($sequence, $operation, $flaglist)

Set flags on a sequence set. For information on the flaglist, see the buildflaglist() method. See DEFINITIONS above for "sequence set".

Operation is one of the following actions to take on the flags:

• FLAGS - Replace the currently set flags of the message(s) with the flaglist.
• +FLAGS - Add the flaglist flags to the currently set flags of the message(s).
• -FLAGS - Remove the flaglist flags from the currently set flags of the message(s).

Under normal circumstances, the command returns the new value of the flags as if a fetch() of those flags was done. You can append a .SILENT operation to any of the above commands to negate this behavior, and not have it return the new flag values.

• FLAGS.SILENT - Equivalent to FLAGS, but without returning a new value
• +FLAGS.SILENT - Equivalent to +FLAGS, but without returning a new value
• -FLAGS.SILENT - Equivalent to -FLAGS, but without returning a new value

  NOTE ON SILENT OPTION: The server SHOULD send an untagged fetch() response if a change to a message's flags from an external source is observed. The intent is that the status of the flags is determinate without a race condition. In other words, .SILENT may still return important (unexpected) flag change information!

copy($sequence, $mailbox)

Copy a sequence set of messages to a mailbox. See DEFINITIONS above for "sequence set"

uidcopy($sequence,$mailbox)

Identical to the copy() command, except set is a UID set rather than a sequence set.

uidfetch($sequence,$fetchstring)

Identical to the fetch() command, except set is a UID set rather than a sequence set.

uidstore($sequence,$operation, $flaglist)

Identical to the store() command, except set is a UID set rather than a sequence set.

uidexpunge($sequence)

Identical to the expunge() command, except you can specify a set of messages to be expunged, rather than the entire mailbox, via a UID set. This function ensures the existance of the UIDPLUS atom in the capability() command.

Note: At this time, the function does not implement the reccomendation in RFC2359, which suggestests that clients use alternate methods in selectivly expunging messages on servers that do not support UIDPLUS.

uidsearch($searchstring)

Identical to the search() command, except the results are returned with UIDs instead of sequence IDs. See the end of this document for valid search terminology.

setacl($mailbox,$user,@permissions)

Modify the access control lists to set the provided permissions for the user on the mailbox, overwriting any previous access controls for the user. See the end of this document for a complete list of possible permissions for use in the permissions list.

deleteacl($mailbox,$user)

Remove all permissions for user on the mailbox's access control list.

getacl($mailbox)

Get the access control list for the supplied mailbox. Returns a two-level hash, with the first level consisting of userIDs, and the second level consisting of a hash of the permissions for the parent userID, in both short and long form.

grant($mailbox,$user,@permissions) (not an official RFC2086 command)

Modify the access control lists to add the specified permissions for the user on the mailbox. See the end of this document for a complete list of possible permissions for use in the permissions list.

revoke($mailbox,$user,@permissions) (not an official RFC2086 command)

Modify the access control lists to remove the specified permissions for the user on the mailbox. If the end result is no permissions for the user, the user will be deleted from the acl list. See the end of this document for a complete list of possible permissions for use in the permissions list.

listrights($mailbox,$user)

Get the list of access controls that may be granted to the supplied user for the supplied mailbox. Returns a hash populated with both short and long rights definitions for testing for the existance of a permision, like $hash{'list'}.

myrights($mailbox)

Get the access control list information for the currently authorized user's access to the supplied mailbox. Returns a hash of the permissions available, in both short and long form.

setquota($mailbox,$type,$quota)

Set the quota on the mailbox. Type is the type of quota to specify, for example STORAGE. Sized-based quota is supplied in KB.

getquota($mailbox)

Get the quota for the supplied mailbox. The provided mailbox must be a quota root, and the authorized user might need to be an administrator, otherwise a "NO" reponse will be returned. getquotaroot() is likely the more applicable command for finding the current quota information on a mailbox. Quota is returned in a hash of lists: The hash elements correspond to the quota type (for example, STORAGE). The list consists of all numbers that corresponded to the quote type.

For example, the RFC specifies that the STORAGE type returns the quota used in the first element, and the maximum quota in the second. Quota units corresponding to sizes are in KB.

getquotaroot($mailbox)

Fetch the list of quotaroots and the quota for the provided mailbox. This command is idential to the getquota() command, except the query doesn't have to be at the quota root, since this command will find the quota root for the specified mailbox, then return the results based on the results of the find. Thus, there will be an extra hash item, 'ROOT', that specified what was used as the quota root. Quota units corresponding to sizes are in KB.

rlist($reference,$mailbox)

List all the mailboxes the authorized user can see for the given mailbox from the given reference. This command lists both local and remote mailboxes, and can also be an indicator to the server that the client (you) supports referrals. Not reccomended if referrals are not supported by the overlying program.

Returns a listref of hasherefs, one per element, where each hashes keys include FLAGS, REFERENCE, and MAILBOX.

IMPORTANT: Referrals come in a "NO" response, so this command will fail even if responded to with a referral. The referral MUST be pulled out of the error(), and can then be parsed by the parse_referral() command if desired, to extract the important pieces for the clients used.

Unless overridden, rlist will check for the MAILBOX-REFERRALS capability() atom before executing the command. If the capability is not advertised, the function will fail without sending the request to the server.

rsub($reference,$mailbox)

List all the subscriptions for the authorized user for the given mailbox from the given reference. This command lists both local and remote subscriptions, and can also be an indicator to the server that the client (you) supports referrals. Not reccomended if referrals are not supported by the overlying program.

Returns a listref of hasherefs, one result per element, where each hashes keys include FLAGS, REFERENCE, and MAILBOX.

IMPORTANT: Referrals come in a "NO" response, so this command will fail even if responded to with a referral. The referral MUST be pulled out of the error(), and can then be parsed by the parse_referral() command if desired, to extract the important pieces for the clients used.

Unless overridden, rlsub will check for the MAILBOX-REFERRALS capability() atom before executing the command. If the capability is not advertised, the function will fail without sending the request to the server.

idle(FIXME)

Issue IDLE command, currently unimplemented.

id(%perams)

Provide identifying information to the server, and have the server do the same to you. The client can request the server's information without sharing its own by supplying an undef perams argument. The information by both parties is useful for statistical or debugging purposes, but otherwise serves no other functional purpose.

The perams arguemnt is a hash, since information is in a key-value format. Keys can be anything, but must be less than 30 characters in length, and values must be less than 1024 characters in length. There are a set keys defined by the RFC that are reccomended: These include:

• name - Name of the program
• version - Version number of the program
• os - Name of the operating system
• os-version - Version of the operating system
• vendor - Vendor of the client/server
• support-url - URL to contact for support
• address - Postal address of contact/vendor
• date - Date program was released, specified as a date-time in IMAP4rev1
• command - Command used to start the program
• arguments - Arguments supplied on the command line, if any
• environment - Description of environment, i.e., UNIX environment List all the subscriptions for the authorized user for the given mailbox from the given reference.variables or Windows registry settings

None of the keys are required - if the client wishes not to supply information for a key, the key is simply omitted. Not all clients support this extention: Support can be identified by using the capability() command, and verifying the atom "ID" is included in the server-supplied list.

getannotation($mailbox, $entry_specifier, $attribute_specifier)

Retrieve annotations on a mailbox from the server. If the mailbox argument is empty, it will retrieve global server annotations instead.

The entry specifier indicates which type of annotation you will retrieve. the "*" wildcard is valid for retrieving all annotations, while the "%" wildcard will match all text except the hierarchy delimiter '/'.

As of draft-ietf-imapext-annotate-15, valid global entries are:

• /comment

  Defines a comment or note associated with the server

• /motd

  Defines a "message of the day" for the server (Read-Only)

• /admin

  Indicates a method for contacting the server administrator (Read-Only)

• /vendor/<vendor-token>

  Defines the top-level of entries associated with the server as created by a particular product of some vendor. Vendor tokens are registered with IANA, using the ACAP [RFC2244] vendor subtree registry.

... and the mailbox entries are ...

• /comment

  Defines a per-mailbox comment, connected with the specified mailbox

• /sort

  Defines the default sort criteria [I-D.ietf-imapext-sort] to use when first displaying the mailbox contents to the user, or NIL if sorting is not required.

• /thread

  Defines the default thread criteria [I-D.ietf-imapext-sort] to use when first displaying the mailbox contents to the user, or NIL if threading is not required. This takes precidence over the /sort annotation.

• /check

  A true/false value that indicates whether this mailbox should be checked at regular intervals by the client.

• /checkperiod

  if /check is true, this numberic value indicates a period of minutes that the client should check the mailbox.

• /vendor/<vendor-token>

  Identical to the global version, except they apply only to the specified mailbox.

The attribute specifier indicates which part of the annotation you wish to receive. As of draft-ietf-imapext-annotate-15, valid global attributes are

• /value

  String or binary data representing the value of the annotation. NIL can be stored to delete an annotation. Text value sshould use the utf-8 character set. Binary data uses the "literal8" syntax element [I-D.melnikov-imap-ext-abnf] to store and retreive such data.

• /size

  the size, in octets, of the value. (Read-only)

• /content-language

  Language used for the value. This SHOULD be set if the value stored is textual.

In addition, all attributes have a '.priv' and a '.shared' suffix, meaning private and shared, respecitvly. If neither attribute suffix is specified, both will be retrieved (if allowed).

Returns a nested hash reference with the mailbox name as the first layer, the entry as the second layer, the attribute name in the third layer.

Structure example:

setannotation($mailbox, $mailbox, \%annoation_hash)

Set annotations on a mailbox from the server. If the mailbox argument is empty, it will attempt to set global server annotations instead.

For details on annotations and its arguments, see the getannotation() command.

The setannotation() command only accepts annotations for one mailbox at a time - as a result, the setannotation() command accepts a mailbox argument and an attribute tree, rather than the entire annotation hash that getannotation returns.

As a result, setannotation takes the same type of hash that getannotation returns, except starting at the mailbox level. For example, the hash must be in the form of

The the first level is for which tags to set, and the second level is what attributes those tags will have, while the value is the actual value to assign.

One key difference between the getannotation() and setannotation() hashes is that the setannotation() mailbox can contain a wildcard - for example, setting 'INBOX.%' as the mailbox will add an annotation for all mailboxes at the top-level of the INBOX hierarchy.

This function is provided for the ease of creating an appropriate aclstring. The set of arguments is the set of permissions to include in the aclstring. The following are the supported rights:

• lookup, list, l - mailbox is visible to list()/lsub()/rlist()/rlsub() commands
• read, r - select() the mailbox, perform check(), fetch(), PARTIAL?, search(), copy() from mailbox
• seen, s - keep seen/unseen information across sessions (store() SEEN flag)
• write, w - store() flags other than SEEN and DELETE
• insert, i - perform append(), copy() into mailbox
• post, p - send mail to submission address for mailbox
• create, c - create() new sub-mailboxes
• delete, d - store() DELETED flag, perform expunge()s
• administer, admin, a - perform setacl() commands
• all - all the above rights. Overrides all other commands
• none - none of the above rights. This is the same as providing no arguments. Is overriden by any other supplied commands
• 0-9 - implementation or site defined rights (nonstandard)

buildfetch([\%body,\%body,...],$other)

Builds a fetch query to get only the data you want. The first argument, the body hash ref, is designed to easily create the body section of the query, and takes the following arguments:

• body

  Specify in a section of the body to fetch(). undef is allowed, meaning no arguments to the BODY option, which will request the full message (unless a header is specified - see below).

• offset

  Specify where in the body to start retrieving data, in octets. Default is from the beginning (0). If the offset is beyond the end of the data, an empty string will be returned. Must be specified with the length option.

• length

  Specify how much data to retrieve starting from the offset, in octets. If the acutal data is less than the length specified, the acutal data will be returned. There is no default value, and thus must be specified if offset is used.

• header

  Takes either 'ALL', 'MATCH', or 'NOT'. 'ALL' will return all the headers, regardless of the contents of headerfields. 'MATCH' will only return those headers that match one of the terms in headerfields, while 'NOT' will return only those headers that *do not* match any of the terms in the headerfields.

• headerfields

  Used when header is 'MATCH' or 'NOT', it specifies the headers to use for comparison. This argument is a string of space-seperated terms.

• peek

  When set to 1, uses the BODY.PEEK command instead of BODY, which preserves the \Seen state of the message

A single hash reference may be supplied for a single body command. If multiple body commands are required, they must be passed inside an array reference (i.e. [\%hash, \%hash]).

If an empty hashref is supplied as a \%body argument, it is interpreted as a BODY[] request.

The final argument, other, is a string of space-seperated stand-alone data items. Valid items via RFC3501 include:

• BODY

  The non-extensible form of BODYSTRUCTURE (not to be confused with the first argument - this command fetches structure, not content)

• BODYSTRUCTURE

  The MIME-IMB body structure of the message.

• ENVELOPE

  The RFC-2822 envelope structure of the message.

• FLAGS

  The flags set for the message

• INTERNALDATE

  The internal date of the message

• RFC822, RFC822.HEADER, RFC822.SIZE, RFC822.TEXT

  RFC822, RFC822.HEADER, and RFC822.TEXT are equivilant to the similarly-named BODY options from the first argument, except for the format they return the results in (in this case, RFC-822). There is no '.PEEK' available, so the \Seen state may be altered. SIZE returns the RFC-822 size of the message and does not change the \Seen state.

• UID

  The unique identifier for the message.

• ALL

  equivalent to FLAGS, INTERNALDATE, RFC822.SIZE, ENVELOPE

• FAST

  equivalent to FLAGS, INTERNALDATE RFC822.SIZE

• FULL

  equivalent to FLAGS, INTERNALDATE, RFC822.SIZE, ENVELOPE, BODY

The final argument, other, provides some basic option-sanity checking and assures that the options supplied are in the proper format. For example, if a program has a list of options to use, a simple buildfetch(undef,join(' ',@args)) would manipulate the terms into a format suitable for a fetch() command. It is highly recommended to pass options through this function rather than appending a pre-formatted string to the functions output to ensure proper formatting.

buildflaglist(@flags)

This function is provided for the ease of creating an appropriate status flags string. Simply provide it with a list of flags, and it will create a legal flags string for use in any append() command, store() command, or any other command that may require status flags.

Since the RFCs don't explicity define valid flags, implementation dependant and custom flags may exist on any given service - therefore this function will blindly interpret any status flag you give it. The server may reject the subsequent command due to an invalid flag.

check_capability($tag)

This function returns a simple true/false answer to whether the supplied tag is found in the capability() list, indicating support for a certain feature. Note: capability() results are cached by the object, however if capability() has not been executed at least once, this will cause it to do so.

parse_referral($referral_line)

Given a referral line (the pre-cursory tag and 'NO' response are optional), this function will return a hash of the important information needed to connect to the referred server. Hash keys for connecting to a referred server include SCHEME, USER, AUTH, HOST, PORT. Other keys for use after successfull connection to the referred server include PATH, QUERY, UID, UIDVALIDITY, TYPE, SECTION. Others are possible if returned within the path as '/;key=value' format.