/ 
Mail-IMAPClient-1.09
River stage one • 9 direct dependents • 9 total dependents
/ Mail::IMAPClient

NAME

Mail::IMAPClient - An IMAP Client API

SYNOPSIS

    use Mail::IMAPClient;
    my $imap = Mail::IMAPClient->new( Server => 'imaphost', 
			  User   => 'memememe',
			  Password => 'secret',
    );

    $imap->Debug($opt_d);

    my @folders = $imap->folders;

    foreach my $f (@folders) { 

	print 	"$f is a folder with ",
		$imap->message_count($f),
		" messages.\n";
   }

DESCRIPTION

This module provides methods implementing the IMAP protocol. It allows perl scripts to interact with IMAP message stores.

The module is used by constructing or instantiating a new IMAPClient object via the new constructor method. Once the object has been instantiated, the connect method is either implicitly or explicitly called. At that point methods are available that implement the IMAP client commands as specified in RFC2060. When processing is complete, the logoff object method is called, either explicitly by the program or implicitly when the object goes out of scope (or at program termination).

This documentation is not meant to be a replacement for RFC2060, and the wily programmer will have a copy of that document handy when coding IMAP clients.

Note that this documentation uses the term folder in place of RFC2060's use of mailbox. This documentation reserves the use the term mailbox to refer to the set of folders owned by a specific IMAP id.

RFC2060 defines four possible states for an IMAP connection: not authenticated, authenticated, selected, and logged out. These correspond to the IMAPClient constants Connected, Authenticated, Selected, and Unconnected, respectively. These constants are implemented as class methods, and can be used in conjunction with the Status method to determine the status of an IMAPClient object and its underlying IMAP session. Note that an IMAPClient object can be in the Unconnected state both before a server connection is made and after it has ended. This differs slightly from RFC2060, which does not define a pre-connection status. For a discussion of the methods available for examining the IMAPClient object's status, see the section labeled "Status Methods", below.

Transactions

RFC2060 requires that each line in an IMAP conversation be prefixed with a tag. A typical conversation consists of the client issuing a tag-prefixed command string, and the server replying with one of more lines of output. Those lines of output will include a command completion status code prefixed by the same tag as the original command string.

The IMAPClient module uses a simple counter to ensure that each client command is issued with a unique tag value. This tag value is referred to by the IMAPClient module as the transaction number. A history is maintained by the IMAPClient object documenting each transaction. The Transaction method returns the number of the last transaction, and can be used to retrieve lines of text from the object's history.

The Clear parameter is used to control the size of the session history so that long-running sessions do not eat up unreasonable amounts of memory. See the discussion of Clear under the Parameters section for more information.

The Report transaction returns the history of the entire IMAP session since the initial connection or the last time the Clear object method was invoked. This provides a record of the entire conversation, including client command strings and server responses, and is a wonderful debugging tool as well as a useful source of raw data for custom parsing.

Class Methods

There are a couple of methods that can be invoked as class methods. Generally they can be invoked as an object method as well, as a convenience to the programmer. (That is, as a convenience to the programmer who wrote this module, as well as the programmers using it. It's easier not to enforce a class method's classiness.) Note that if the new method is called as an object method, the object returned is identical to what have would been returned if new had been called as a class method. It doesn't give you a copy of the original object or anything like that.

new

The new method creates a new instance of an IMAPClient object. If the Server parameter is passed as an argument to new, then new will implicitly call the connect method. If the Server parameter is not supplied then the IMAPClient object is created in the Unconnected state.

Unconnected

returns a value equal to the numerical value associated with an object in the Unconnected state.

Connected

returns a value equal to the numerical value associated with an object in the Connected state.

Authenticated

returns a value equal to the numerical value associated with an object in the Authenticated state.

Selected

returns a value equal to the numerical value associated with an object in the Selected state.

Strip_cr

The <Strip_cr> method strips carriage returns from IMAP client command output. Although RFC2060 specifies that lines in an IMAP conversation end with <CR><LF>, it is often cumbersome to have the carriage returns in the returned data. This method accepts a line of text as an argument, and returns that line with all carriage returns removed. If the input argument had no carriage returns then it is returned unchanged.

Strip_cr does not remove new line characters.

Rfc822_date

The Rfc822_date method accepts one input argument, a number of seconds since the epoch date. It returns an RFC822 compliant date string for that date (without the 'Date:' prefix). Useful for putting dates in messagestrings before calling <append>.

Parameters

There are several parameters that influence the behavior of an IMAPClient object. Each is set by specifying a named value pair during new method invocation as follows:

my $imap = Mail::IMAPClient->new ( parameter  => "value",
		       parameter2 => "value",
			...
	);

Parameters can also be set after an object has been instantiated by using the parameter's eponymous accessor method like this:

my $imap = Mail::IMAPClient->new;
   $imap->parameter( "value");
   $imap->parameter2("value");

The eponymous accessor methods can also be used without arguments to obtain the current value of the parameter as follows:

	my $imap = Mail::IMAPClient->new;
           $imap->parameter( "value");
           $imap->parameter2("value");

		... 	# A whole bunch of awesome perl code, 
			# omitted for brevity
	   

	   my $forgot  = $imap->parameter;
	   my $forgot2 = $imap->parameter2;

Note that in these examples I'm using 'parameter' and 'parameter2' as generic parameter names. The IMAPClient object doesn't actually have parameters named 'parameter' and 'parameter2'. On the contrary, the available parameters are:

Debug

Sets the debugging flag to either a true or false value. Can be supplied with the new method call or separately by calling the Debug object method.

Port

Specifies the port on which the IMAP server is listening. The default is 143, which is the standard IMAP port. Can be supplied with the new method call or separately by calling the Port object method.

Server

Specifies the hostname or IP address of the host running the IMAP server. If provided as part of the new method call, then the new IMAP object will automatically be connected at the time of instantiation. (See the new method, below.) Can be supplied with the new method call or separately by calling the Server object method.

Timeout

Specifies the timeout value in seconds for reads. Specifying a true value for Timeout will prevent Mail::IMAPClient from blocking in a read.

Since timeouts are implemented via the perl select operator, the Timeout parameter may be set to a fractional number of seconds. Not supplying a Timeout, or (re)setting it to zero, disables the timeout feature.

User

Specifies the userid to use when logging into the IMAP service. Can be supplied with the new method call or separately by calling the User object method.

Password

Specifies the password to use when logging into the IMAP service on the host specified in the Server parameter as the user specified in the User parameter. Can be supplied with the new method call or separately by calling the Password object method.

If Server, User, and Password are all provided to the new method, then the newly instantiated object will be connected to the host specified in Server (at either the port specified in Port or the default port 143) and then logged on as the user specified in the User parameter (using the password provided in the Password parameter). See the discussion of the new method, below.

Clear

Specifies that the object's history buffer should be cleared and the transaction count reset to 0 after every n transactions, where n is the value specified for the Clear parameter. Resetting Clear to a true value during a session (even if it is reset to the current value) by calling the eponymous Clear method with an argument will clear the history buffer of its contents immediately. Calling the eponymous Clear method without an argument will return the current value of the Clear parameter but will not immediately clear the history buffer.

Setting Clear to 0 turns off automatic history buffer clearing, and setting it to 1 turns off the history buffer facility (except for the last transaction, which cannot be disabled without breaking the IMAPClient module). Setting Clear to 0 will not cause an immediate clearing of the history buffer; setting it to 1 (or any other number) will.

The default Clear value is set to five in order to conserve memory.

Uid

If Uid is set to a true value (i.e. 1) then the behavior of the fetch, search, copy, and store methods (and their derivatives) is changed so that arguments that would otherwise be message sequence numbers are treated as message UID's and so that return values (in the case of the search method and its derivatives) that would normally be message sequence numbers are instead message UID's.

Internally this is implemented as a switch that, if turned on, causes methods that would otherwise issue an IMAP FETCH, STORE, SEARCH, or COPY client command to instead issue UID FETCH, UID STORE, UID SEARCH, or UID COPY, respectively. The main difference between message sequence numbers and message UID's is that, according to RFC2060, UID's must not change during a session and should not change between sessions, and must never be reused. Sequence numbers do not have that same guarantee and in fact may be reused right away.

Since foldernames also have a unique identifier (UIDVALIDITY), which is provided when the folder is selected or examined or by doing something like "$imap->status($folder,"UIDVALIDITY"), it is possible to uniquely identify every message on the server, although normally you won't need to bother.

The methods currently affected by turning on the Uid flag are:

copy 		fetch
search 		store 
message_string 	message_uid
body_string 	flags
move 		size

Note that if for some reason you only want the Uid parameter turned on for one command, then you can choose between the following two snippets, which are equivalent:

Example 1:

$imap->Uid(1);
my @hits = $imap->search('SUBJECT',"Just a silly test");
$imap->Uid(0);

Example 2:

	my @hits 
       	foreach $r ($imap->uid("SEARCH","SUBJECT","Just a silly test") {
	       chomp $r;
	       $r =~ s/\r$//;
	       $r =~ s/^\*\s+SEARCH\s+// or next;
	       push @hits, grep(/\d/,(split(/\s+/,$r)));
	}

In the second example, we used the default method to issue the UID IMAP Client command, being careful to use different case so as not to inadvertently call the Uid accessor method. Then we parsed out the message UID's manually, since we don't have the benefit of the built-in search method doing it for us.

Please be very careful when turning the Uid parameter on and off throughout a script. If you loose track of whether you've got the Uid parameter turned on you might do something sad, like deleting the wrong message. Remember, like all eponymous accessor methods, the Uid method without arguments will return the current value for the Uid parameter, so do yourself a favor and check. The safest approach is probably to turn it on at the beginning and then leave it on. (Remember that leaving it turned off can lead to problems if changes to a folder's contents cause resequencing.)

Socket

The Socket method can be used to obtain the socket handle of the current connection (say, to do I/O on the connection that is not otherwise supported by Mail::IMAPClient) or to replace the current socket with a new handle (perhaps an SSL handle, for example).

If you supply a socket handle yourself, either by doing something like:

$imap=Mail::IMAPClient->new(Socket=>$sock, User => ... );

or by doing something like:

$imap=Mail::IMAPClient->new(User => $user, Password => $pass, Server => $host);
# blah blah blah
$imap->Socket($ssl);

then it will be up to you to establish the connection AND to authenticate, either via the login method, or the fancier authenticate, or, since you know so much anyway, by just doing raw I/O against the socket.

Parameters can be set during new method invocation by passing named parameter/value pairs to the method, or later by calling the parameter's eponymous object method.

Object Methods

Object methods must be invoked against objects created via the new method. They cannot be invoked as class methods, which is why they are "object methods" and not "class methods".

There are basically two types of object methods--those that participate in the IMAP session's conversation (i.e. they issue IMAP client commands) and those that do not. Methods that do not result in new IMAP client commands being issued (such as the Transaction, Status, and History methods) all begin with an uppercase letter, to distinguish themselves from methods that do correspond to IMAP client commands. (Class methods and eponymous parameter methods likewise begin with an uppercase letter because they also do not correspond to an IMAP client command.)

The IMAPClient object methods are:

append

The append method adds a message to the specified folder. It takes two arguments, the name of the folder to append the message to, and the text of the message (including headers). Additional arguments are added to the message text, separated with a newline.

The append method returns the UID of the new message (a true value) if successful, or undef if not, if the IMAP server has the UIDPLUS capability.

authenticate

The authenticate method accepts two arguments, an authentication type to be used (ie CRAM-MD5) and a code or subroutine reference to execute to obtain a response. The authenticate assumes that the authentication type specified in the first argument follows a challenge-response flow. The authenticate method issues the IMAP Client AUTHENTICATE command and receives a challenge from the server. That challenge (minus any tag prefix or enclosing '+' characters but still base64 encoding) is passed as the only argument to the code or subroutine referenced in the second argument. The return value from the 2nd argument's code is written to the server as is, except that a <CR><NL> sequence is appended if neccessary.

before

The before method works just like the since method, below, except it returns a list of messages whose internal system dates are before the date supplied as the argument to the before method.

body_string

The body_string method accepts a message sequence number (or a message UID, if the Uid parameter is set to true) as an argument a returns the message body as a string. The returned value contains the entire message in one scalar variable, without the message headers.

capability

The capability method returns an array of capabilities as returned by the CAPABILITY IMAP Client command, or a reference to an array of capabilities if called in scalar context. If the CAPABILITY IMAP Client command fails for any reason then the capability method will return undef.

connect

The connect method connects an imap object to the server. It returns undef if it fails to connect for any reason. If values are available for the User and Password parameters at the time that connect is invoked, then connect will call the login method after connecting and return the result of the login method to connect's caller. If either or both of the User and Password parameters are unavailable but the connection to the server succeeds then connect returns a pointer to the IMAPClient object.

The Server parameter must be set (either during new method invocation or via the Server object method) before invoking connect. If the Server parameter is supplied to the new method then connect is implicitly called during object construction.

The connect method sets the state of the object to connected if it successfully connects to the server.

copy

The copy method requires a folder name as the first argument, and a list of one or more messages sequence numbers (or messages UID's, if the UID parameter is set to a true value). The message sequence numbers or UID's should refer to messages in the currenly selected folder. Those messages will be copies into the folder named in the first argument to the copy method.

The copy method returns undef on failure and a true value if successful. If the server to which the current Mail::IMAPClient object is connected supports the UIDPLUS capability then the true value returned by copy will be a comma separated list of UID's, which are the UID's of the newly copied messages in the target folder.

delete_message

The delete_message method accepts a list of arguments. If the Uid parameter is not set to a true value, then each item in the list should be either:

a message sequence number,
a comma-separated list of message sequence numbers,
a reference to an array of message sequence numbers, or

If the Uid parameter is set to a true value, then each item in the list should be either:

a message UID,
a comma-separated list of UID's, or
a reference to an array of message UID's.

The messages identified by the sequence numbers or UID's will be deleted. delete_message returns the number of messages it was told to delete. However, since the delete is done by issuing the +FLAGS.SILENT option of the STORE IMAP client command, there is no guarantee that the delete was successful. In this manner the delete_message method sacrifices accuracy for speed. If you must have guaranteed results then use the IMAP STORE client command (via the default method) and use the +FLAGS (\Deleted) option, and then parse your results manually. Eg:

$imap->store($msg_id,'+FLAGS (\Deleted)');
my @results = $imap->History($imap->Transaction);
...			# code to parse output goes here

The IMAPClient object must be in Selected status to use the delete_message method.

NOTE: All the messages identified in the input argument(s) must be in the currently selected folder. Failure to comply to this requirement will almost certainly result in the wrong message(s) being deleted. This would be a crying shame.

NOTE SOME MORE: In the grand tradition of the IMAP protocol, deleting a message doesn't actually delete the message. Really. If you want to make sure the message has been deleted, you need to expunge the folder (via the expunge method, which is implemented via the default method).

See also: The delete method, to delete a folder, and expunge and close in RFC2060.

disconnect

Disconnects the IMAPClient object from the server. Functionally equivalent to the logout method.

examine

The examine method selects a folder in read-only mode and changes the object's state to "Selected". The folder selected via the examine method can be examined but no changes can be made unless it is first selected via the select method.

The examine method accepts one argument, which is the name of the folder to select.

exists

Accepts one argument, a folder name. Returns true if the folder exists or false if it does not exist.

fetch

The fetch method implements the FETCH IMAP client command. It accepts a list of arguments, which will be converted into a space-delimited list of arguments to the FETCH IMAP client command. If no arguments are supplied then fetch does a FETCH ALL. If the Uid parameter is set to a true value then the first argument will be treated as a UID or list of UID's, which means that the UID FETCH IMAP client command will be run instead of FETCH. (It would really be a good idea at this point to review RFC2060.)

flags

The flags method implements the FETCH IMAP client command to list a single message's flags. It accepts one argument, a message sequence number (or a message UID, if the Uid parameter is true), and returns an array (or a reference to an array, if called in scalar context) listing the flags that have been set. Flag names are provided with leading backslashes, if any.

folders

The folders method returns an array listing the available folders. It will only be successful if the object is in the Authenticated or Selected states.

has_capability

Returns true if the IMAP server to which the IMAPClient object is connected has the capability specified as an argument to has_capability.

is_parent

The is_parent method accepts one argument, the name of a folder. It returns a value that indicates whether or not the folder has children. The value it returns is either 1) a true value (indicating that the folder has children), 2) 0 if the folder has no children at this time, or 3) undef if the folder is not permitted to have children.

Eg: my $parenthood = $imap->is_parent($folder); if (defined($parenthood)) { if ($parenthood) { print "$folder has children.\n" ; } else { print "$folder is permitted children, but has none.\n"; } } else { print "$folder is not permitted to have children.\n"; }

list

The list method implements the IMAP LIST client command. Arguments are passed to the IMAP server as received, separated from each other by spaces. If no arguments are supplied then the default list command tag LIST "" '*' is issued.

The list method returns an array (or an array reference, if called in a scalar context). The array is the unaltered output of the LIST command.

login

The login method uses the IMAP LOGIN client command (as defined in RFC2060) to log into the server. The User and Password parameters must be set before the login method can be invoked. If successful, the login method returns a pointer to the IMAPClient object and sets the object status to Authenticated. If unsuccessful, it returns undef.

logout

The logout method issues the LOGOUT IMAP client commmand. Since the LOGOUT IMAP client command causes the server to end the connection, this also results in the IMAPClient client entering the Unconnected state. This method does not, however, destroy the IMAPClient object, so a program can re-invoke the connect and login methods if it wishes to reestablish a session later in the program.

message_count

The message_count method accepts the name of a folder as an argument and returns the number of messages in that folder. Internally, it invokes the status method (see above) and parses out the results to obtain the number of messages.

message_string

The message_string method accepts a message sequence number (or message UID if Uid is true) as an argument a returns the message as a string. The returned value contains the entire message in one scalar variable, including the message headers.

message_uid

The message_uid method accepts a message sequence number (or message UID if Uid is true) as an argument and returns the message's UID. Yes, if Uid is true then it will use the IMAP UID FETCH UID client command to obtain and return the very same argument you supplied. This is an IMAP feature so don't complain to me about it.

move

The move method moves messages from the currently selected folder to the folder specified in the first argument to move. If the Uid parameter is not true, then the rest of the arguments should be either:

a message sequence number,
a comma-separated list of message sequence numbers, or
a reference to an array of message sequence numbers.

If the Uid parameter is true, then the arguments should be:

a message UID,
a comma-separated list of message UID's, or
a reference to an array of message UID's.

If the target folder does not exist then it will be created.

If move is sucessful, then it returns a true value. Furthermore, if the Mail::IMAPClient object is connected to a server that has the UIDPLUS capability, then the true value will be the list of UID's for the newly copied messages. The list will be in the order in which the messages were moved. (Since move uses the copy method, the messages will be moved in numerical order.)

If the move is not successful then move returns undef.

on

The on method works just like the since method, below, except it returns a list of messages whose internal system dates are the same as the date supplied as the argument to the on method.

parse_headers

The parse_headers method accepts as arguments a message sequence number and a list of header fields. It returns a hash reference in which the keys are the header field names (without the colon) and the values are references to arrays of values. A picture would look something like this:

   $hashref = $imap->parse_headers(1,"Date","Received","Subject","To");
   $hashref = {
	"Date" 	 	=> [ "Thu, 09 Sep 1999 09:49:04 -0400" ]  ,
        "Received"	=> [ q/
	   	from mailhub ([111.11.111.111]) by mailhost.bigco.com 
	   	(Netscape Messaging Server 3.6)  with ESMTP id AAA527D for 
	   	<bigshot@bigco.com>; Fri, 18 Jun 1999 16:29:07 +0000
	   	/, q/
	   	from directory-daemon by mailhub.bigco.com (PMDF V5.2-31 #38473)
 	   	id <0FDJ0010174HF7@mailhub.bigco.com> for bigshot@bigco.com
 	   	(ORCPT rfc822;big.shot@bigco.com); Fri, 18 Jun 1999 16:29:05 +0000 (GMT)
	   	/, q/
	   	from someplace ([999.9.99.99]) by smtp-relay.bigco.com (PMDF V5.2-31 #38473) 
	        with ESMTP id <0FDJ0000P74H0W@smtp-relay.bigco.com> for big.shot@bigco.com; Fri,
	   	18 Jun 1999 16:29:05 +0000 (GMT)
	   	/] ,
	"Subject" 	=> [ qw/ Help! I've fallen and I can't get up!/ ] ,
	"To"		=> [ "Big Shot <big.shot@bigco.com> ] ,
	} ;

The text in the example for the "Received" array has been formated to make reading the example easier. The actual values returned are just strings of words separated by spaces and with newlines and carriage returns stripped off. The Received header is probably the main reason that the parse_headers method creates a hash of lists rather than a hash of values.

If the second argument to parse_headers is 'ALL' or if it is unspecified then all available headers are included in the returned hash of lists.

If you're not emotionally prepared to deal with a hash of lists then you can always call the fetch method yourself with the appropriate parameters and parse the data out any way you want to.

If the Uid parameter is true then the first argument will be treated as a message UID.

Currently, specifying a range of message numbers as the first argument is not supported.

recent

The recent method performs an IMAP SEARCH RECENT search against the selected folder and returns an array of sequence numbers (or UID's, if the Uid parameter is true) of messages that are recent.

recent_count

The recent_count method accepts as an argument a folder name. It returns the number of recent messages in the folder (as returned by the IMAP client command "STATUS folder RECENT"), or undef in the case of an error. The recent_count method was contributed by Rob Deker (deker@ikimbo.com).

rename

The rename method accepts two arguments: the name of an existing folder, and a new name for the folder. The existing folder will be renamed to the new name using the RENAME IMAP client command. rename will return a true value if successful, or undef if unsuccessful.

run

Like Perl itself, the Mail::IMAPClient module is designed to make common things easy and uncommon things possible. The run method is provided to make those uncommon things possible.

The run method excepts one or two arguments. The first argument is a string containing an IMAP Client command, including a tag and all required arguments. The optional second argument is a string to look for that will indicate success. (The default is OK.*). The run method returns an array of output lines from the command, which you are free to parse as you see fit.

The run method does not do any syntax checking, other than rudimentary checking for a tag.

When run processes the command, it increments the transaction count and saves the command and responses in the History buffer in the same way other commands do. However, it also creates a special entry in the History buffer named after the tag supplied in the string passed as the first argument. If you supply a numeric value as the tag then you may risk overwriting a previous transaction's entry in the History buffer, unless the numeric value is greater then the value of the Clear parameter and Clear is not 0.

If you want the control of run but you don't want to worry about the damn tags then see the tag_and_run method, below.

The search method implements the SEARCH IMAP client command. Any argument supplied to search is prefixed with a space and appended to the SEARCH IMAP client command. This method is another one of those situations where it will really help to have your copy of RFC2060 handy, since the SEARCH IMAP client command contains a plethora of options and possible arguments.

Remember that if your argument needs quotes around it then you must make sure that the quotes will be preserved when passing the argument. I.e. use qq/"$arg"/ instead of "$arg".

The search method returns an array containing sequence numbers of messages that passed the SEARCH IMAP client command's search criteria. If the Uid parameter is true then the array will contain message UID's. If search is called in scalar context then a pointer to the array will be passed, instead of the array itself.

seen

The seen method performs an IMAP SEARCH SEEN search against the selected folder and returns an array of sequence numbers of messages that have already been seen (ie their SEEN flag is set). If the Uid parameter is true then an array of message UID's will be returned instead. If called in scalar context than a pointer to the array (rather than the array itself) will be returned.

select

The select method selects a folder and changes the object's state to "Selected". It accepts one argument, which is the name of the folder to select.

sentbefore

The sentbefore works just like sentsince, below, except it searches for messages that were sent before the date supplied as an argument to the method.

senton

The senton works just like sentsince, below, except it searches for messages that were sent on the exact date supplied as an argument to the method.

sentsince

The sentsince method accepts one argument, a date in either standard perl format (seconds since 1/1/1970, or as output by time and as accepted by localtime) or in the date_text format as defined in RFC2060 (dd-Mon-yyyy, where Mon is the English-language three-letter abbreviation for the month).

It searches for items in the currently selected folder for messages sent since the day whose date is provided as the argument. It uses the RFC822 Date: header to determine the senton date.

In the case of arguments supplied as a number of seconds, the returned result list will include items sent on or after that day, regardless of whether they arrived before the specified time on that day. The IMAP protocol does not support searches at a granularity finer than a day, so neither do I.

separator

The separator method returns the character used as a separator character in folder hierarchies. On unix-based servers, this is often a forward slash (/). It accepts one argument, the name of a folder whose hierarchy's separator should be returned. If no folder name is supplied then the separator for the INBOX is returned, which probably is good enough.

setacl

The setacl method accepts three input arguments, a folder name, a user id (or authentication identifier, to use the terminology of RFC2086), and an access rights modification string. See RFC2086 for more information.

since

The since method accepts a date in either standard perl format (seconds since 1/1/1970, or as output by time and as accepted by localtime) or in the date_text format as defined in RFC2060 (dd-Mon-yyyy, where Mon is the English-language three-letter abbreviation for the month). It searches for items in the currently selected folder for messages whose internal dates are on or after the day whose date is provided as the argument. It uses the internal system date for a message to determine if that message was sent since the given date.

In the case of arguments supplied as a number of seconds, the returned result list will include items whose internal date is on or after that day, regardless of whether they arrived before the specified time on that day. The IMAP protocol does not support searches at a granularity finer than a day, so neither do I.

size

The size method accepts one input argument, a sequence number (or message UID if the Uid parameter is true). It returns the size of the message in the currently selected folder with the supplied sequence number (or UID). The IMAPClient object must be in a Selected state in order to use this method.

status

The status method accepts one argument, the name of a folder (or mailbox, to use RFC2060's terminology), and returns an array containing the results of running the IMAP STATUS client command against that folder. If additional arguments are supplied then they are appended to the IMAP STATUS client command string, separated from the rest of the string and each other with spaces.

If status is not called in an array context then it returns a reference to an array rather than the array itself.

The status method should not be confused with the Status method (with an uppercase 'S'), which returns information about the IMAPClient object. (See the section labeled Status Methods, below).

tag_and_run

The tag_and_run method accepts one or two arguments. The first argument is a string containing an IMAP Client command, without a tag but with all required arguments. The optional second argument is a string to look for that will indicate success. (The default is OK.*).

The tag_and_run method will prefix your string (from the first argument) with the next transaction number and run the command. It returns an array of output lines from the command, which you are free to parse as you see fit. Using this method instead of run (above) will free you from having to worry about handling the tags (and from worrying about the side affects of naming your own tags).

uidnext

The uidnext method accepts one argument, the name of a folder, and returns the numeric string that is the next available message UID for that folder.

uidvalidity

The uidvalidity method accepts one argument, the name of a folder, and returns the numeric string that is the unique identifier validity value for the folder.

unseen

The unseen method performs an IMAP SEARCH UNSEEN search against the selected folder and returns an array of sequence numbers of messages that have not yet been seen (ie their SEEN flag is not set). If the Uid parameter is true then an array of message UID's will be returned instead. If called in scalar context than a pointer to the array (rather than the array itself) will be returned.

Other IMAP Client Commands

IMAP Client Commands not otherwise documented have been implemented via an AUTOLOAD hack and use a default method.

If a program calls a method that is not defined (or inherited) by the IMAPClient module then the IMAPClient module will assume that it is an IMAP client command. It will prefix the command with the next available transaction number (or tag value), and append to it the space-delimited list of arguments supplied to the unimplemented method. It will then read lines of output from the imap session until it finds a line containing the strings "OK" and "Completed", and return an array containing all of the lines of output (or, if called in scalar context, an array reference).

Eg:

$imap->FOO("bar","an example","of the default");

results in:

"99 FOO bar an example of the default\r\n"

being sent to the IMAP server (assuming that 99 is the current transaction number).

CAUTION: Once again, remember to quote your quotes if you want quotes to be part of the IMAP command string.

You can also use the default method to override the behavior of implemented IMAP methods by changing the case of the method name, preferably to all-uppercase so as not to conflict with the Class method and accessor method namespace. For example, if you don't want the search method's behavior (which returns a list of message numbers) but would rather have an array of raw data returned from your search operator, you can issue the following snippet:

@raw = $imap->SEARCH("SUBJECT","Whatever...");

which is slightly more efficient than the equivalent:

my @msgs = $imap->search("SUBJECT","Whatever...");

my @raw = $imap->Results;
Status Methods

There are several object methods that return the status of the object. They can be used at any time to check the status of an IMAPClient object, but are particularly useful for determining the cause of failure when a connection and login are attempted as part of a single new method invocation. The status methods are:

1. Status

returns a numerical value that indicates the current status of the IMAPClient object. (Not to be confused with the status method, all lower-case, which is the implementation of the STATUS IMAP client command.)

2. IsUnconnected

returns a true value if the object is currently in an Unconnected state.

3. IsConnected

returns a true value if the object is currently in either a Connected, Authenticated, or Selected state.

4. IsAuthenticated

returns a true value if the object is currently in either an Authenticated or Selected state.

5. IsSelected

returns a true value if the object is currently in a Selected state.

6. Transaction

returns the tag value (or transaction number) of the last IMAP client command.

7. Report

The Report method returns an array containing a history of the IMAP session up to the point that Report was called. It is primarily meant to assist in debugging but can also be used to retrieve raw output for manual parsing. The value of the Clear parameter controls how often the contents of Report are cleared. (See the discussion of Clear in the Parameters section, above.)

8. Results

The Results method returns an array containing the results of one IMAP client command. It accepts one argument, the transaction number of the command whose results are to be returned. If transaction number is unspecified then Results returns the results of the last IMAP client command issued. If called in a scalar context, Results returns an array reference rather than an array.

9. History

The History method is almost identical to the Results method. Unlike the Results method, however, the IMAP command that was issued to create the results being returned is not included in the returned results. If called in a scalar context, History returns an array reference rather than an array.

AUTHOR

David J. Kernen
The Kernen Consulting Group, Inc
david.kernen@erols.com

COPYRIGHT

Copyright 1999, The Kernen Group, Inc.
     All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  • a) the "Artistic License" which comes with this Kit, or

  • b) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 1308:

'=item' outside of any '=over'

Around line 1351:

You forgot a '=back' before '=head2'