Subversion Repositories sysadmin_scripts

package Mail::IMAPClient;

# $Id: IMAPClient.pod,v 20001010.1 2003/06/12 21:35:53 dkernen Exp $

$Mail::IMAPClient::VERSION = '2.2.7';

$Mail::IMAPClient::VERSION = '2.2.7';  	# do it twice to make sure it takes

=head1 NAME 

Mail::IMAPClient - An IMAP Client API

=head1 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 L<new> constructor method. Once the object has been

instantiated, the L<connect> method is either implicitly or explicitly

called. At that point methods are available that implement the IMAP

client commands as specified in I<RFC2060>. When processing is

complete, the I<logoff> object method should be called.

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 I<folder> in place of

RFC2060's use of I<mailbox>. This documentation reserves the use of the

term I<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 B<IMAPClient> constants C<Connected>,

C<Authenticated>, C<Selected>, and C<Unconnected>, respectively. These

constants are implemented as class methods, and can be used in

conjunction with the L<Status> method to determine the status of an

B<IMAPClient> object and its underlying IMAP session. Note that an

B<IMAPClient> object can be in the C<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 B<IMAPClient>

object's status, see the section labeled L<"Status Methods">, below.

=head2 Advanced Authentication Mechanisms

RFC2060 defines two commands for authenticating to an IMAP server: LOGIN for

plain text authentication and AUTHENTICATE for more secure authentication

mechanisms. Currently Mail::IMAPClient supports CRAM-MD5 and plain text 

authentication. There are also a number of methods and parameters that you 

can use to build your own authentication mechanism. Since this topic is a source

of many questions, I will provide a quick overview here. All of the methods and

parameters discussed here are described in more detail elsewhere in this document;

this section is meant to help you get started.

First of all, if you just want to do plain text authentication and your server is

okay with that idea then you don't even need to read this section. 

Second of all, the intent of this section is to help you implement the authentication

mechanism of your choice, but you will have to understand how that mechanism works.

There are I<lots> of authentication mechanisms and most of them are not available to

me to test with for one reason or another. Even if this section does not answer

all of your authentication questions it I<does> contain all the answers that I have,

which I admit are scant.

Third of all, if you manage to get any advanced authentication mechanisms to work then

please consider donating them to this module. I don't quite have a framework visualized

for how different authentication mechanisms could "plug in" to this module but I would

like to eventually see this module distributed with a number of helper modules to 

implement various authentication schemes.

The B<Mail::IMAPClient>'s support for add-on authentication mechanisms is pretty straight

forward and is built upon several assumptions. Basically you create a callback to be used to

provide the response to the server's challenge. The I<Authcallback> parameter contains a 

reference to the callback, which  can be an anonymous subroutine or a named subroutine. 

Then, you identify your authentication mechanism, either via the I<Authmechanism> parameter 

or as an argument to L<authenticate>. 

You may also need to provide a subroutine to encrypt (or whatever) data before it is sent

to the server. The I<Prewritemethod> parameter must contain a reference to this subroutine.

And, you will need to decrypt data from the server; a reference to the subroutine that 

does this must be stored in the I<Readmethod> parameter.

This framework is based on the assumptions that a) the mechanism you are using requires

a challenge-response exchange, and b) the mechanism does not fundamentally alter the 

exchange between client and server but merely wraps the exchange in a layer of 

encryption. It particularly assumes that the line-oriented nature of the IMAP conversation

is preserved; authentication mechanisms that break up messages into blocks of a 

predetermined size may still be possible but will certainly be more difficult to implement.

Alternatively, if you have access to B<imtest>, a utility included in the Cyrus IMAP

distribution, you can use that utility to broker your communications with the IMAP server.

This is quite easy to implement. An example, L<examples/imtestExample.pl>, can be found in 

the C<examples> subdirectory of the source distribution. 

The following list summarizes the methods and parameters that you may find useful in 

implementing advanced autentication:

=over 4

=item authenticate method

This method implements the AUTHENTICATE IMAP client command as documented in RFC2060.

If you have set the I<Authmechanism> parameter then the L<login> method will call

L<authenticate> instead of doing a clear text login, which is its normal behavior.

If you don't want B<login> to call B<authenticate> on your behalf then you can call

it yourself. Instead of setting an I<Authmechanism> you can just pass the authmechanism

as the first argument to AUTHENTICATE. 

=item Socket Parameter

The I<Socket> parameter holds a reference to the socket connection. Normally this

is set for you by the L<connect> method, but if you are implementing an advanced 

authentication technique you may choose to set up your own socket connection and then

set this parameter manually, bypassing the B<connect> method completely.

=item State, Server, Password, and User Parameters

If you need to make your own connection to the server and perform your authentication

manually, then you can set these parameters to keep your B<Mail::IMAPClient> object

in sync with its actual status. Of these, only the I<State> parameter is always necessary.

The others need to be set only if you think your program will need them later.

=item Authmechanism 

Set this to the value that AUTHENTICATE should send to the server as the authentication

mechanism. If you are brokering your own authentication then this parameter may be less

useful. It is also not needed by the L<authenticate> method. It exists solely so that you

can set it when you call L<new> to instantiate your object. The B<new> method will call

L<connect>, who will call L<login>. If B<login> sees that you've set an I<Authmechanism>

then it will call B<authenticate>, using your I<Authmechanism> and I<Authcallback> 

parameters as arguments.

=item Authcallback 

The I<Authcallback> parameter, if set, should contain a pointer to a subroutine. The

L<login> method will use this as the callback argument to the B<authenticate> method

if the I<Authmechanism> and I<Authcallback> parameters are both set. If you set

I<Authmechanism> but not I<Authcallback> then the default callback for your mechanism

will be used. Unfortunately only the CRAM-MD5 authentication mechanism has a default

callback; in every other case not supplying the callback results in an error.

Most advanced authentication mechanisms require a challenge-response exchange. After the

L<authenticate> method sends "<tag> AUTHENTICATE <Authmechanism>\r\n"  to the IMAP 

server, the server replies with a challenge. The B<authenticate> method then invokes 

the code whose reference is stored in the I<Authcallback> parameter as follows:

	$Authcallback->($challenge,$imap)

where C<$Authcallback> is the code reference stored in the I<Authcallback> parameter,

C<$challenge> is the challenge received from the IMAP server, and C<$imap> is a pointer

to the B<Mail::IMAPClient> object. The return value from the I<Authcallback> routine 

should be the response to the challenge, and that return value will be sent by the 

L<authenticate> method to the server.

=item Readmethod 

The I<Readmethod> parameter points to a routine that will read data from the socket

connection. This read method will replace the B<sysread> that would otherwise be

performed by B<Mail::IMAPClient>. The replacement method is called with five 

arguments. The first is a pointer to the B<Mail::IMAPClient> object; the rest

are the four arguments required by the B<sysread> function. Note the third argument

(which corresponds to the second argument to B<sysread>) is a buffer to read into;

this will be a pointer to a scalar. So for example if your I<Readmethod> were just 

going to replace B<sysread> without any intervening processing (which would be silly

but this is just an example after all) then you would set your I<Readmethod> like this:

	$imap->Readmethod( 

		sub { 

			my($self) = shift; 

			my($handle,$buffer,$count,$offset) = @_;

			return sysread( $handle, $$buffer, $count, $offset);

		}

	);

Note particularly the double dollar signs in C<$$buffer> in the B<sysread> call; this

is not a typo!

=item Prewritemethod

The I<Prewritemethod>, if defined, should contain a pointer to a subroutine.

It is called immediately prior to writing to the

socket connection. It is called by B<Mail::IMAPClient> with two arguments:

a reference to the B<Mail::IMAPClient> object and the ASCII text string to be written. 

It should return another string that will be the actual string sent to the IMAP server. 

The idea here is that your I<Prewritemethod> will do whatever encryption is necessary 

and then return the result to the caller so it in turn can be sent to the server.

=back

=head2 Errors

If you attempt an operation that results in an error, then you can

retrieve the text of the error message by using the L<LastError>

method. However, since the L<LastError> method is an object method (and

not a class method) you will only be able to use this method if you've

successfully created your object. Errors in the L<new> method can

prevent your object from ever being created. Additionally, if you

supply the I<Server>, I<User>, and I<Password> parameters to L<new>, it

will attempt to call B<connect> and B<login>, either of which could

fail and cause your L<new> method call to return C<undef> (in which case

your object will have been created but its reference will have been

discarded before ever having been returned to you).

If this happens to you, you can always check C<$@>. B<Mail::IMAPClient>

will populate that variable with something useful if either of the

L<new>, L<connect>, or L<login> methods fail. In fact, as of version 2,

the C<$@> variable will always contain error info from the last error,

so you can print that instead of calling L<LastError> if you wish. 

If you run your script with warnings turned on (which I'm sure you'll

do at some point because it's such a good idea) then any error message

that gets placed into the L<LastError> slot (and/or in C<$@>) will

automatically generate a warning. 

=head2 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 B<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 B<IMAPClient> module as the transaction number. A

history is maintained by the B<IMAPClient> object documenting each

transaction. The L<Transaction> method returns the number of the last

transaction, and can be used to retrieve lines of text from the

object's history. 

The L<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 L<Clear> under L<"Parameters">

for more information.

The L<Report> transaction returns the history of the entire IMAP

session since the initial connection or for the last I<Clear>

transactions. 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.

=head1 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 I<not> to enforce a class method's classiness.) Note that

if the L<new> method is called as an object method, the object returned

is identical to what have would been returned if L<new> had been called

as a class method. It doesn't give you a copy of the original object or

anything like that.

=head2 new

Example:

	Mail::IMAPClient->new(%args) or die "Could not new: $@\n";

The L<new> method creates a new instance of an B<IMAPClient> object. If

the I<Server> parameter is passed as an argument to B<new>, then B<new>

will implicitly call the L<connect> method, placing the new object in

the I<Connected> state. If I<User> and I<Password> values are also

provided, then L<connect> will in turn call L<login>, and the resulting

object will be returned from B<new> in the I<Authenticated> state.

If the I<Server> parameter is not supplied then the B<IMAPClient>

object is created in the I<Unconnected> state.

If the B<new> method is passed arguments then those arguments will be

treated as a list of key=>value pairs. The key should be one of the

parameters as documented under L<"Parameters">, below. 

Here are some examples:

	use Mail::IMAPClient;

	# returns an unconnected Mail::IMAPClient object:

	my $imap = Mail::IMAPClient->new;	

	#	...				

	# intervening code using the 1st object, then:

	# (returns a new, authenticated Mail::IMAPClient object)

	$imap = Mail::IMAPClient->new(	

			Server => $host,

			User 	=> $id,

			Password=> $pass,

			Clear	=> 5,	# Unnecessary since '5' is the default

	#		...		# Other key=>value pairs go here

	)	or die "Cannot connect to $host as $id: $@";

See also L<"Parameters">, below, and L<"connect"> and L<"login"> for

information on how to manually connect and login after B<new>.

=cut

=head2 Authenticated

Example:

	$Authenticated = $imap->Authenticated();

	# or:

	$imap->Authenticated($new_value);  # But you'll probably never need to do this

returns a value equal to the numerical value associated with an object

in the B<Authenticated> state. This value is normally maintained by the

B<Mail::IMAPClient> module, so you typically will only query it and 

won't need to set it.

B<NOTE:> For a more programmer-friendly idiom, see the L<IsUnconnected>,

L<IsConnected>, L<IsAuthenticated>, and L<IsSelected> object methods. You 

will usually want to use those methods instead of one of the above.

=head2 Connected

Example:

	$Connected = $imap->Connected();

	# or:

	$imap->Connected($new_value); # But you'll probably never need to do this 

returns a value equal to the numerical value associated with an object

in the B<Connected> state.  This value is normally maintained by the

B<Mail::IMAPClient> module, so you typically will only query it and 

won't need to set it.

B<NOTE:> For a more programmer-friendly idiom, see the L<IsUnconnected>,

L<IsConnected>, L<IsAuthenticated>, and L<IsSelected> object methods. You 

will usually want to use those methods instead of one of the above.

=head2 Quote

Example:

	$imap->search(HEADER => 'Message-id' => $imap->Quote($msg_id));

The B<Quote> method accepts a value as an argument.  It returns its 

argument as a correctly quoted string or a literal string.

Note that you should not use this on folder names, since methods that accept

folder names as an argument will quote the folder name arguments appropriately

for you. (Exceptions to this rule are methods that come with IMAP extensions 

that are not explicitly supported by B<Mail::IMAPClient>.)

If you are getting unexpected results when running methods with values that 

have (or might have) embedded spaces, double quotes, braces, or parentheses, 

then you may wish to call B<Quote> to quote these values. You should B<not> 

use this method with foldernames or with arguments that are wrapped in quotes 

or parens if those quotes or parens are there because the RFC2060 spec requires 

them. So, for example, if RFC requires an argument in this format:

	( argument )

and your argument is (or might be) "pennies (from heaven)", then you could just

use: 

	$argument = "(" . $imap->Quote($argument) . ")" 

and be done with it.

Of course, the fact that sometimes these characters are sometimes required 

delimiters is precisely the reason you must quote them when they are I<not> 

delimiting. For example:

	$imap->Search('SUBJECT',"(no subject)");

	# WRONG! Sends this to imap server: 

	#<TAG> Search SUBJECT (no subject)\r\n

	$imap->Search('SUBJECT',$imap->Quote("(no subject)"));

	# Correct! Sends this to imap server: 

	#<TAG> Search SUBJECT "(no subject)"\r\n

On the other hand:

	$imap->store('+FLAGS',$imap->Quote("(\Deleted)"));

	# WRONG! Sends this to imap server: 

	#<TAG> [UID] STORE +FLAGS "(\Deleted)"\r\n

	$imap->store($imap->Quota('+FLAGS'),"(\Deleted)");

	# CORRECT! Sends this to imap server: 

	#<TAG> [UID] STORE +FLAGS (\Deleted)\r\n

In the above, I had to abandon the many methods available to 

B<Mail::IMAPClient> programmers (such as L<delete_message> and all-lowercase 

L<search>) for the sake of coming up with an example. However, there are 

times when unexpected values in certain places will force you to B<Quote>. 

An example is RFC822 Message-id's, which I<usually> don't contain quotes or 

parens. So you don't worry about it, until suddenly searches for certain 

message-id's fail for no apparent reason. (A failed search is not simply a 

search that returns no hits; it's a search that flat out didn't happen.) 

This normally happens to me at about 5:00 pm on the one day when I was hoping 

to leave on time. (By the way, my experience is that any character that can 

possibly find its way into a Message-Id eventually will, so when dealing

with these values take proactive, defensive measures from the very start.

In fact, as I was typing the above, a buddy of mine came in to ask advice about

a logfile parsing routine he was writing in which the fields were delimited

by colons. One of the fields was a Message Id, and, you guessed it, some of the

message id's in the log had (unescaped!) colons embedded in them and were 

screwing up his C<split()>.  So there you have it, it's not just me. This is 

everyone's problem.)

=head2 Range

Example:

	my %parsed = $imap->parse_headers(

				$imap->Range($imap->messages),

				"Date",

				"Subject"

	);

The B<Range> method will condense a list of message sequence numbers or

message UID's into the most compact format supported by RFC2060. It accepts

one or more arguments, each of which can be:

=over 8

=item a) a message number,

=item b) a comma-separated list of message numbers,

=item c) a colon-separated range of message numbers (i.e. "$begin:$end")

=item d) a combination of messages and message ranges, separated by commas

(i.e. 1,3,5:8,10), or

=item e) a reference to an array whose elements are like I<a)> through I<d)>.

=back

The B<Range> method returns a reference to a B<Mail::IMAPClient::MessageSet>

object. The object has all kinds of magic properties, one of which being that

if you treat it as if it were just a string it will act like it's just a 

string. This means you can ignore its objectivity and just treat it like a

string whose value is your message set expressed in compact format.

You may want to use this method if you find that fetch operations on large

message sets seem to take a really long time, or if your server rejects

these requests with the claim that the input line is too long. You may also

want to use this if you need to add or remove messages to your message set

and want an easy way to manage this. 

For more information on the capabilities of the returned object reference,

see L<Mail::IMAPClient::MessageSet>.

=head2 Rfc2060_date

Example:

	$Rfc2060_date = $imap->Rfc2060_date($seconds);

	# or:

	$Rfc2060_date = Mail::IMAPClient->Rfc2060_date($seconds);

The B<Rfc2060_date> method accepts one input argument, a number of

seconds since the epoch date. It returns an RFC2060 compliant date

string for that date (as required in date-related arguments to SEARCH,

such as "since", "before", etc.). 

=head2 Rfc822_date

Example:

	$Rfc822_date = $imap->Rfc822_date($seconds);

	# or:

	$Rfc822_date = Mail::IMAPClient->Rfc822_date($seconds);

The B<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 message strings before calling L<append>, L<search>, etcetera.

=head2 Selected

Example:

	$Selected = $imap->Selected();

	# or:

	$imap->Selected($new_value); # But you'll probably never need to do this

returns a value equal to the numerical value associated with an object

in the B<Selected> state.  This value is normally maintained by the

B<Mail::IMAPClient> module, so you typically will only query it and 

won't need to set it.

B<NOTE:> For a more programmer-friendly idiom, see the L<IsUnconnected>,

L<IsConnected>, L<IsAuthenticated>, and L<IsSelected> object methods. You 

will usually want to use those methods instead of one of the above.

=head2 Strip_cr

Example:

	$Strip_cr = $imap->Strip_cr();

	# or:

	$imap->Strip_cr($new_value);

The B<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 one or more lines of text as

arguments, and returns those lines with all <CR><LF> sequences changed

to <LF>. Any input argument with no carriage returns is returned

unchanged. If the first argument (not counting the class name or object

reference) is an array reference, then members of that array are

processed as above and subsequent arguments are ignored. If the method

is called in scalar context then an array reference is returned instead

of an array of results.

Taken together, these last two lines mean that you can do something

like:

	my @list = $imap->some_imap_method ;

        @list = $imap->Strip_cr(@list) ; 

	# or: 

	my $list = [ $imap->some_imap_method ] ; # returns an array ref

	$list = $imap->Strip_cr($list);

B<NOTE: Strip_cr> does not remove new line characters.

=cut

=head2 Unconnected

Example:

	$Unconnected = $imap->Unconnected();

	# or:

	$imap->Unconnected($new_value);

returns a value equal to the numerical value associated with an object

in the B<Unconnected> state.  This value is normally maintained by the

B<Mail::IMAPClient> module, so you typically will only query it and 

won't need to set it.

B<NOTE:> For a more programmer-friendly idiom, see the L<IsUnconnected>,

L<IsConnected>, L<IsAuthenticated>, and L<IsSelected> object methods. You 

will usually want to use those methods instead of one of the above.

=head1 OBJECT METHODS

Object methods must be invoked against objects created via the L<new>

method. They cannot be invoked as class methods, which is why they are

called "object methods" and not "class methods". 

There are basically two types of object methods--mailbox methods, which 

participate in the IMAP session's conversation (i.e. they issue IMAP 

client commands) and object control methods, which do not result in 

IMAP commands but which may affect later commands or provide details

of previous ones. This latter group can be further broken down into

two types, Parameter accessor methods, which affect the behavior of 

future mailbox methods, and Status methods, which report on the affects

of previous mailbox methods.

Methods that do not result in new IMAP client commands being issued 

(such as the L<Transaction>, L<Status>, and L<History> methods) all 

begin with an uppercase letter, to distinguish them 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.

As a general rule, mailbox control methods return C<undef> on failure 

and something besides C<undef> when they succeed. This rule is modified 

in the case of methods that return search results. When called in a list 

context, searches that do not find matching results return an empty list. 

When called in a scalar context, searches with no hits return 'undef' 

instead of an array reference. If you want to know why you received no hits,

you should check C<$@>, which will be empty if the search was successful

but had no matching results but populated with an error message if the 

search encountered a problem (such as invalid parameters).

A number of IMAP commands do not have corresponding B<Mail::IMAPClient>

methods. Instead, they are implemented via a default method and Perl's 

L<AUTOLOAD|perlsub/autoload> facility. If you are looking for a specific

IMAP client command (or IMAP extension) and do not see it documented in this

pod, then that does not necessarily mean you can not use B<Mail::IMAPClient> to

issue the command. In fact, you can issue almost any IMAP client

command simply by I<pretending> that there is a corresponding 

B<Mail::IMAPClient> method.  See the section on 

L<"Other IMAP Client Commands and the Default Object Method">

below for details on the default method.

=head1 Mailbox Control Methods

=head2 append

Example:

	my $uid = $imap->append($folder,$msg_text) 

		or die "Could not append: $@\n";

The B<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 <CR><LF>.

The B<append> method returns the UID of the new message (a true value)

if successful, or C<undef> if not, if the IMAP server has the UIDPLUS

capability. If it doesn't then you just get true on success and undef

on failure.

Note that many servers will get really ticked off if you try to append

a message that contains "bare newlines", which is the titillating term

given to newlines that are not preceded by a carrage return. To protect

against this, B<append> will insert a carrage return before any newline

that is "bare". If you don't like this behavior then you can avoid it

by not passing naked newlines to B<append>.

Note that B<append> does not allow you to specify the internal date or

initial flags of an appended message. If you need this capability then

use L<append_string>, below.

=cut

=head2 append_file

Example:

	my $new_msg_uid = $imap->append_file(

		$folder,

		$filename 

		[ , $input_record_separator ]	# optional (not arrayref)

	) 	or die "Could not append_file: $@\n";

The B<append_file> method adds a message to the specified folder. It

takes two arguments, the name of the folder to append the message to,

and the file name of an RFC822-formatted message.

An optional third argument is the value to use for

C<input_record_separator>. The default is to use "" for the first read

(to get the headers) and "\n" for the rest. Any valid value for C<$/>

is acceptable, even the funky stuff, like C<\1024>. (See L<perlvar|perlvar> 

for more information on C<$/>). (The brackets in the example indicate

that this argument is optional; they do not mean that the argument 

should be an array reference.)

The B<append_file> method returns the UID of the new message (a true

value) if successful, or C<undef> if not, if the IMAP server has the

UIDPLUS capability. If it doesn't then you just get true on success and

undef on failure. If you supply a filename that doesn't exist then you

get an automatic C<undef>. The L<LastError> method will remind you of this

if you forget that your file doesn't exist but somehow manage to

remember to check L<LastError>.

In case you're wondering, B<append_file> is provided mostly as a way to

allow large messages to be appended without having to have the whole

file in memory. It uses the C<-s> operator to obtain the size of the

file and then reads and sends the contents line by line (or not,

depending on whether you supplied that optional third argument).

=cut

=head2 append_string

Example:

	# brackets indicate optional arguments (not array refs):

	my $uid = $imap->append_string( $folder, $text [ , $flags [ , $date ] ]) 	

		or die "Could not append_string: $@\n";

The B<append_string> method adds a message to the specified folder. It

requires two arguments, the name of the folder to append the message

to, and the text of the message (including headers). The message text

must be included in a single string (unlike L<append>, above).

You can optionally specify a third and fourth argument to

B<append_string>. The third argument, if supplied, is the list of flags

to set for the appended message. The list must be specified as a

space-separated list of flags, including any backslashes that may be

necessary. The enclosing parentheses that are required by RFC2060 are

optional for B<append_string>. The fourth argument, if specified, is

the date to set as the internal date. It should be in the format

described for I<date_time> fields in RFC2060, i.e. "dd-Mon-yyyy

hh:mm:ss +0000".

If you want to specify a date/time but you don't want any flags then

specify I<undef> as the third argument.

The B<append_string> method returns the UID of the new message (a true

value) if successful, or C<undef> if not, if the IMAP server has the

UIDPLUS capability. If it doesn't then you just get true on success and

undef on failure.

Note that many servers will get really ticked off if you try to append

a message that contains "bare newlines", which is the titillating term

given to newlines that are not preceded by a carrage return. To protect

against this, B<append_string> will insert a carrage return before any

newline that is "bare". If you don't like this behavior then you can

avoid it by not passing naked newlines to B<append_string>.

=cut

=head2 authenticate

Example:

	$imap->authenticate($authentication_mechanism, $coderef) 

		or die "Could not authenticate: $@\n";

The B<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 B<authenticate> method assumes that 

the authentication type specified in the first argument follows a

challenge-response flow. The B<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 in the original 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.

If one or both of the arguments are not specified in the call to

B<authenticate> but their corresponding parameters have been set

(I<Authmechanism> and I<Authcallback>, respectively) then the parameter

values are used. Arguments provided to the method call however will

override parameter settings.

If you do not specify a second argument and you have not set the 

I<Authcallback> parameter, then the first argument must be

one of the authentication mechanisms for which B<Mail::IMAPClient> has

built in support. Currently there is only built in support for CRAM-MD5, 

but I hope to add more in future releases. 

If you are interested in doing NTLM authentication then please see Mark

Bush's L<Authen::NTLM>, which can work with B<Mail::IMAPClient> to

provide NTLM authentication.

See also the L<login> method, which is the simplest form of

authentication defined by RFC2060.

=cut

=head2 before

Example:

	my @msgs = $imap->before($Rfc2060_date) 

		or warn "No messages found before $Rfc2060_date.\n";

The B<before> method works just like the L<"since"> method, below,

except it returns a list of messages whose internal system dates are

before the date supplied as the argument to the B<before> method.

=cut

=head2 body_string

Example:

	my $string = $imap->body_string($msgId) 

		or die "Could not body_string: $@\n";

The B<body_string> method accepts a message sequence number (or a

message UID, if the L<Uid> parameter is set to true) as an argument and

returns the message body as a string. The returned value contains the

entire message in one scalar variable, without the message headers.

=cut

=head2 bodypart_string

Example:

	my $string=$imap->bodypart_string( 	$msgid, $part_number , 

						$length ,$offset  

	) 	or die "Could not get bodypart string: $@\n";

The B<bodypart_string> method accepts a message sequence number (or a

message UID, if the L<Uid> parameter is set to true) and a body part as

arguments and returns the message part as a string. The returned value

contains the entire message part (or, optionally, a portion of the part) 

in one scalar variable.

If an optional third argument is provided, that argument is the number

of bytes to fetch. (The default is the whole message part.) If an

optional fourth argument is provided then that fourth argument is the

offset into the part at which the fetch should begin. The default is

offset zero, or the beginning of the message part.

If you specify an offset without specifying a length then the offset

will be ignored and the entire part will be returned.

B<bodypart_string> will return C<undef> if it encounters an error.

=cut

=head2 capability

Example:

	my @features = $imap->capability

		or die "Could not determine capability: $@\n";

The B<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 B<capability> method will return

C<undef>.

=head2 close

Example:

	$imap->close or die "Could not close: $@\n";

The B<close> method is implemented via the default method and is used

to close the currently selected folder via the CLOSE IMAP client

command. According to RFC2060, the CLOSE command performs an implicit

EXPUNGE, which means that any messages that you've flagged as

I<\Deleted> (say, with the L<delete_message> method) will now be

deleted. If you haven't deleted any messages then B<close> can be

thought of as an "unselect".

Note again that this closes the currently selected folder, not the 

IMAP session.

See also L<delete_message>, L<expunge>, and your tattered copy of

RFC2060.

=head2 connect

Example:

	$imap->connect or die "Could not connect: $@\n";

The B<connect> method connects an imap object to the server. It returns

C<undef> if it fails to connect for any reason. If values are available

for the I<User> and I<Password> parameters at the time that B<connect>

is invoked, then B<connect> will call the L<login> method after

connecting and return the result of the L<login> method to B<connect>'s

caller. If either or both of the I<User> and I<Password> parameters are

unavailable but the connection to the server succeeds then B<connect>

returns a pointer to the B<IMAPClient> object.

The I<Server> parameter must be set (either during L<new> method

invocation or via the L<Server> object method) before invoking

B<connect>. If the L<Server> parameter is supplied to the L<new> method

then B<connect> is implicitly called during object construction.

The B<connect> method sets the state of the object to C<connected> if

it successfully connects to the server. It returns C<undef> on failure.

=head2 copy

Example:

	# Here brackets indicate optional arguments:

	my $uidList = $imap->copy($folder, $msg_1 [ , ... , $msg_n ]) 

	or die "Could not copy: $@\n";

Or:

	# Now brackets indicate an array ref!

	my $uidList = $imap->copy($folder, [ $msg_1, ... , $msg_n ]) 

	or die "Could not copy: $@\n";

The B<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 I<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 copied into the folder named in the

first argument.

The B<copy> method returns C<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 B<copy> will be a comma separated list of UID's, which are

the UID's of the newly copied messages in the target folder. 

=cut

=head2 create

Example:

	$imap->create($new_folder) 

		or die "Could not create $new_folder: $@\n";

The B<create> method accepts one argument, the name of a folder (or

what RFC2060 calls a "mailbox") to create. If you specifiy additional

arguments to the B<create> method and your server allows additional

arguments to the CREATE IMAP client command then the extra argument(s)

will be passed to your server. 

If you specifiy additional arguments to the B<create> method and your

server does not allow additional arguments to the CREATE IMAP client

command then the extra argument(s) will still be passed to your server

and the create will fail, so don't do that.

B<create> returns a true value on success and C<undef> on failure, as

you've probably guessed.

=head2 date

Example:

	my $date = $imap->date($msg);

The B<date> method accepts one argument, a message sequence number (or a

message UID if the I<Uid> parameter is set to a true value). It returns 

the date of message as specified in the message's RFC822 "Date: " header,

without the "Date: " prefix.

The B<date> method is a short-cut for:

	my $date = $imap->get_header($msg,"Date");

=head2 delete

Example:

	$imap->delete($folder) or die "Could not delete $folder: $@\n";

The B<delete> method accepts a single argument, the name of a folder to

delete. It returns a true value on success and C<undef> on failure.

=head2 delete_message

Example:

	my @msgs = $imap->seen;

	scalar(@msgs) and $imap->delete_message(\@msgs) 

		or die "Could not delete_message: $@\n";

The above could also be rewritten like this:

	# scalar context returns array ref

	my $msgs = scalar($imap->seen);	

	scalar(@$msgs) and $imap->delete_message($msgs) 

		or die "Could not delete_message: $@\n";

Or, as a one-liner:

	$imap->delete_message( scalar($imap->seen) )

		or warn "Could not delete_message: $@\n";

	# just give warning in case failure is 

	# due to having no 'seen' msgs in the 1st place!

The B<delete_message> method accepts a list of arguments. If the L<Uid>

parameter is not set to a true value, then each item in the list should

be either: 

=over 4

=item > a message sequence number,

=item > a comma-separated list of message sequence numbers, 

=item > a reference to an array of message sequence numbers, or

=back

If the L<Uid> parameter is set to a true value, then each item in the

list should be either: 

=over 4

=item > a message UID, 

=item > a comma-separated list of UID's, or 

=item > a reference to an array of message UID's.

=back

The messages identified by the sequence numbers or UID's will be

deleted. If successful, B<delete_message> returns the number 

of messages it was told to delete. However, since the delete is 

done by issuing the I<+FLAGS.SILENT> option of the STORE IMAP 

client command, there is no guarantee that the delete was successful 

for every message. In this manner the B<delete_message> method sacrifices 

accuracy for speed. Generally, though, if a single message in a list 

of messages fails to be deleted it's because it was already deleted,

which is what you wanted anyway so why worry about it? If there is

a more severe error, i.e. the server replies "NO", "BAD", or, 

banish the thought, "BYE", then B<delete_message> will return C<undef>.

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

(Frankly I see no reason to bother with any of that; if a message doesn't get 

deleted it's almost always because it's already not there, which is what you 

want anyway. But 'your milage may vary' and all that.)

The B<IMAPClient> object must be in C<Selected> status to use the

B<delete_message> method. 

B<NOTE:> All the messages identified in the input argument(s) must be

in the currently selected folder. Failure to comply with this

requirement will almost certainly result in the wrong message(s) being

deleted. This would be a crying shame. 

B<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 L<expunge> method, which is implemented via the default

method). Or at least L<close> it. This is generally considered a

feature, since after deleting a message, you can change your mind and

undelete it at any time before your L<expunge> or L<close>.