IMAP::Client - Advanced manipulation of IMAP services w/ referral support
use IMAP::Client my $imap = new IMAP::Client($server); unless (ref $imap) { die "Failed to create object: $imap\n"; } (or) my $imap - new IMAP::Client(); imap->connect(PeerAddr => $server, ConnectMethod => 'SSL STARTTLS PLAIN', ) or die "Unable to connect to [$server]: ".$imap->error(); $imap->onfail('ERROR'); $imap->errorstyle('STACK'); $imap->debuglevel(1); $imap->capability_checking(1); $imap->authenticate($user,$pass) or die "Unable to authenticate as $user ".$imap->error()."\n"; (or) $imap->authenticate($user,$pass,$authas_user) or die "Unable to authenticate as $user on behalf of $authas_user: ".$imap->error()."\n"; $imap->id() or die $imap->error(); $imap->capability() or die $imap->error(); $imap->noop() or die $imap->error(); FIXME: more examples here
This module was created as a low-level inteface to any IMAP server. It was built to be a 'clear box' solution to working with an IMAP environment. The idea is that anything an IMAP client should be able to do, and any information available via the IMAP specs, should be available to a client interface and user. This way, the full strength of the IMAP protocol and data can be utilized, ideally in the most network-efficient mannger possible, rather than being contrained only to a subset of commands or data-limited responses. If the server says it, the client should be able to see it.
This module also takes steps to be able to handle anticipated situations for the user rather than forcing a per-implementation behavior for such expected events, such as referrals. IMAP::Client will fully support referrals, and will transparently handle them for whatever command is issued to them (so long as the referral s for anonymous or the same user with the same password - a new user or different password would require a new username/password to be obtained. As of 0.01, this is not supported, however the framework is down.
This module also tries to follow the various RFCs for IMAPrev1 communications very closely, enforcing client-side responsabilities where appropriate. The complete lists of RFCs referenced for this module include:
RFC 3501 - INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
RFC 2086 - IMAP4 ACL extension (0.01)
RFC 2087 - IMAP4 QUOTA extension (0.01)
RFC 2088 - IMAP4 non-synchronizing literals (0.01)
RFC 2177 - IMAP4 IDLE command (Not supported yet)
RFC 2192 - IMAP4 URL Scheme (0.01)
RFC 2193 - IMAP4 Mailbox Referrals (0.01 [Partial])
RFC 2342 - IMAP4 Namespace (Not directly supported yet)
RFC 2359 - IMAP4 UIDPLUS extension (Partial in 0.01 - UID EXPUNGE check ok, need COPYUID and APPENDUID support)
RFC 2971 - IMAP4 ID extension (0.01)use Net::IMAP::Advanced;
RFC 3348 - IMAP4 Child Mailbox Extention (Not directly supported yet)
RFC 3502 - IMAP MULTIAPPEND extention (Not directly supported yet)
RFC 3516 - Binary Content Extention (Not directly supported yet)
RFC 3691 - Internet Message Access Protocol (IMAP) UNSELECT command (Not directly supported yet)
sequence set - A comma-seperated list of numbers and number ranges. A number range is in the format number:number, such as "2:4", meaning messages 2 through 4.
These are the lowest-level functions for use by the program. These offer the most raw access for interacting with an IMAP service, short of doing it manually.
Sends the string argument provided to the server. A tag is automatically prepended to the command.
Send the string argument provided to the server without a tag. This is needed for some operations.
Accept responses from the server until the previous tag is encountered, at which point return the entire response. CAUTION: can cause your program to hang if a tagged response isn't given. For example, if the command expects more input and issues a '+' response, and waits for input, this function will never return.
Accept a line of response, regardless if a tag is provided. Misuse of this function can cause the module to be confused, especially if it received a tagged response and imap_receive() is subsequently used before another imap_send(). Applicable use of this function would be to read an (expected) untagged '+ go ahead' response. If a tagged response is (unexpectedly) received, such as in a NO or BAD response, an imap_send() must be used before the next imap_receive(). You have been warned.
These are the methods for manipulating the object or retrieving information from the object.
new()
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. Valid values are 0 (for no debugging) or 1 (for a communications 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:
Sets the priority of the login methods via a space seperated priority-ordered list. Valid methods are 'SSL', 'STARTTLS', and 'PLAIN'. The default is to try loggin in via SSL, then connecting to the standard IMAP port and negotiating STARTTLS. 'PLAIN' is entirly unencrypted, and is not a default option - it must be specified if desired.
The 'STARTTLS' method uses the starttls() command to negotiate the insecure connection to a secure status - it is functionally equivlant to using the 'PLAIN' method and subsequently calling starttls() within the program.
Set the IMAPS port to use when connecting via the SSL method (default 993).
Set the IMAP port to use when connecting via the STARTTLS or PLAIN methods (default 143).
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($server)
Disconnect from the specified server. Must match the server name used to connect.
These are the standard IMAP commands from the IMAP::Client object. Methods return various structures, simple and complex, depending on the method. All methods return undef on failure, setting error(), barring an override via the onfail() function.
capability()
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()
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().
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:
<n> FLAGS
<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.
examine($mailbox)
Identical to select(), except the mailbox is opened READ-ONLY.
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 list of hashes, 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 list of hashes, 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.
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 list 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)));
FIXME: elaborate? examples, maybe?
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.
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 the permissions for the parent userID.
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.
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 list of hashes, 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 list of hashes, one result per element, where each hashes keys include FLAGS, REFERENCE, and MAILBOX.
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.
These are the support methods created to support the coder in creating some of the more complex and open-ended arguments for the above command methods.
buildacl(@acls)
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:
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).
The final argument, other, is a string of space-seperated stand-alone data items. Valid items via RFC3501 include:
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.
equivalent to FLAGS, INTERNALDATE, RFC822.SIZE, ENVELOPE
equivalent to FLAGS, INTERNALDATE RFC822.SIZE
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.
<sequence set> - Messages with message sequence numbers corresponding to the specified message sequence number set.
ALL - All messages in the mailbox; the default initial key for ANDing.
ANSWERED - Messages with the \Answered flag set.
BCC <string> - Messages that contain the specified string in the envelope structure's BCC field.
BEFORE <date> - Messages whose internal date (disregarding time and timezone) is earlier than the specified date.
BODY <string> - Messages that contain the specified string in the body of the message.
CC <string> - Messages that contain the specified string in the envelope structure's CC field.
DELETED - Messages with the \Deleted flag set.
DRAFT - Messages with the \Draft flag set.
FLAGGED - Messages with the \Flagged flag set.
FROM <string> - Messages that contain the specified string in the envelope structure's FROM field.
HEADER <field-name> <string> - Messages that have a header with the specified field-name (as defined in [RFC-2822]) and that contains the specified string in the text of the header (what comes after the colon). If the string to search is zero-length, this matches all messages that have a header line with the specified field-name regardless of the contents.
KEYWORD <flag> - Messages with the specified keyword flag set.
LARGER <n> - Messages with an [RFC-2822] size larger than the specified number of octets.
NEW - Messages that have the \Recent flag set but not the \Seen flag. This is functionally equivalent to "(RECENT UNSEEN)".
NOT <search-key> - Messages that do not match the specified search key.
OLD - Messages that do not have the \Recent flag set. This is functionally equivalent to "NOT RECENT" (as opposed to "NOT NEW").
ON <date> - Messages whose internal date (disregarding time and timezone) is within the specified date.
OR <search-key1> <search-key2> - Messages that match either search key.
RECENT - Messages that have the \Recent flag set.
SEEN - Messages that have the \Seen flag set.
SENTBEFORE <date> - Messages whose [RFC-2822] Date: header (disregarding time and timezone) is earlier than the specified date.
SENTON <date> - Messages whose [RFC-2822] Date: header (disregarding time and timezone) is within the specified date.
SENTSINCE <date> - Messages whose [RFC-2822] Date: header (disregarding time and timezone) is within or later than the specified date.
SINCE <date> - Messages whose internal date (disregarding time and timezone) is within or later than the specified date.
SMALLER <n> - Messages with an [RFC-2822] size smaller than the specified number of octets.
SUBJECT <string> - Messages that contain the specified string in the envelope structure's SUBJECT field.
TEXT <string> - Messages that contain the specified string in the header or body of the message.
TO <string> - Messages that contain the specified string in the envelope structure's TO field.
UID <sequence set> - Messages with unique identifiers corresponding to the specified unique identifier set. Sequence set ranges are permitted.
UNANSWERED - Messages that do not have the \Answered flag set.
UNDELETED - Messages that do not have the \Deleted flag set.
UNDRAFT - Messages that do not have the \Draft flag set.
UNFLAGGED - Messages that do not have the \Flagged flag set.
UNKEYWORD <flag> - Messages that do not have the specified keyword flag set.
UNSEEN - Messages that do not have the \Seen flag set.
Copyright 2005-2006, Brenden Conte <conteb at cpan dot org> All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl, IO::Socket, IO::Socket::SSL, MIME::Base64, URI, URI::imap, URI::Escape
3 POD Errors
The following errors were encountered while parsing the POD:
You can't have =items (as at line 648) unless the first thing after the =over is an =item
You can't have =items (as at line 997) unless the first thing after the =over is an =item
You can't have =items (as at line 2067) unless the first thing after the =over is an =item
To install IMAP::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IMAP::Client
CPAN shell
perl -MCPAN -e shell install IMAP::Client
For more information on module installation, please visit the detailed CPAN module installation guide.