Mail::IMAPClient(3) User Contributed Perl Documentation Mail::IMAPClient(3)NAMEMail::IMAPClient - An IMAP Client API
SYNOPSIS
use Mail::IMAPClient;
my $imap = Mail::IMAPClient->new(
Server => 'localhost',
User => 'username',
Password => 'password',
Ssl => 1,
Uid => 1,
);
my $folders = $imap->folders
or die "List folders error: ", $imap->LastError, "\n";
print "Folders: @$folders\n";
$imap->select( $Opt{folder} )
or die "Select '$Opt{folder}' error: ", $imap->LastError, "\n";
$imap->fetch_hash("FLAGS", "INTERNALDATE", "RFC822.SIZE")
or die "Fetch hash '$Opt{folder}' error: ", $imap->LastError, "\n";
$imap->logout
or die "Logout error: ", $imap->LastError, "\n";
DESCRIPTION
This module provides methods implementing the IMAP protocol to support
interacting 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 RFC3501. When processing is complete,
the "logout" object method should be called.
This documentation is not meant to be a replacement for RFC3501 nor any
other IMAP related RFCs.
Note that this documentation uses the term folder in place of RFC3501's
use of mailbox. This documentation reserves the use of the term
mailbox to refer to the set of folders owned by a specific IMAP id.
Connection State
RFC3501 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 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 RFC3501, 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.
Advanced Authentication Mechanisms
RFC3501 defines two commands for authenticating to an IMAP server:
LOGIN
LOGIN is for plain text authentication.
AUTHENTICATE
AUTHENTICATE for more advanced and/or secure authentication
mechanisms.
Mail::IMAPClient supports the following AUTHENTICATE mechanisms:
DIGEST-MD5
DIGEST-MD5 authentication requires the Authen::SASL and Digest::MD5
modules. See also "Authuser".
CRAM-MD5
CRAM-MD5 requires the Digest::HMAC_MD5 module.
PLAIN (SASL)
PLAIN (SASL) authentication allows the optional use of the "Proxy"
parameter. RFC 4616 documents this syntax for SASL PLAIN:
message = [authzid] UTF8NUL authcid UTF8NUL passwd
When "Proxy" is defined, "User" is used as 'authzid' and "Proxy" is
used as 'authcid'. Otherwise, "User" is used as 'authcid'.
NTLM
NTLM authentication requires the Authen::NTLM module. See also
"Domain".
Errors
If you attempt an operation that results in an error, then you can
retrieve the text of the error message by using the "LastError" method.
However, the "LastError" method is an object method (not a class
method) and can only be used once an object is successfully created.
In cases where an object is not successfully created the $@ variable is
set with an error message.
Mail::IMAPClient resets $@ and "LastError" to undef before most IMAP
requests, so the values only have a short lifespan. "LastError" will
always contain error info from the last error, until another error is
encountered, another IMAP command is issued or it is explicitly
cleared.
Please note that the use of $@ is subject to change in the future
release so it is best to use "LastError" for error checking once a
Mail::IMAPClient object has been created.
Errors in the "new" method can prevent your object from ever being
created. If the "Server", "User", and "Password" parameters are
supplied to "new", it will attempt to call "connect" and "login". Any
of these methods could fail and cause the "new" method call to return
"undef" and leaving the variable $@ is set to an error message.
WARNING: (due to historical API behavior) on errors, many methods may
return undef regardless of LIST/SCALAR context. Therefore, it may be
wise to use most methods in a scalar context. Regardless, check
"LastError" for details on errors.
Transactions
RFC3501 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" parameter for more
information.
The "Report" transaction returns the history of the entire IMAP session
since the initial connection or for the last "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.
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. 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.
new
Example:
my $imap = Mail::IMAPClient->new(%args)
or die "new failed: $@\n";
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, placing the new object in
the Connected state. If "User" and "Password" values are also
provided, then "connect" will in turn call "login", and the resulting
object will be returned from new in the Authenticated state.
If the "Server" parameter is not supplied then the IMAPClient object is
created in the Unconnected state.
If the 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 "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 "Parameters", "connect" and "login" for more information on
how to manually connect and login after new.
Quote
Example:
$imap->search( HEADER => 'Message-id' => \$imap->Quote($msg_id) );
The Quote method accepts a value as an argument and returns its
argument as a correctly quoted string or a literal string. Since
version 3.17 Mail::IMAPClient automatically quotes search arguments we
use a SCALARREF so search will not modify or re-quote the value
returned by Quote.
Note this method should not be used on folder names for
Mail::IMAPClient methods, since methods that accept folder names as an
argument will quote the folder name arguments appropriately
automatically.
If you are getting unexpected results when running methods with values
that have (or might have) embedded spaces, double quotes, braces, or
parentheses, then calling Quote may be necessary. This method should
not be used with arguments that are wrapped in quotes or parens if
those quotes or parens are required by RFC3501. For example, if the
RFC requires an argument in this format:
( argument )
and the argument is (or might be) "pennies (from heaven)", then one
could use:
$argument = "(" . $imap->Quote($argument) . ")"
Of course, the fact that sometimes these characters are sometimes
required delimiters is precisely the reason you must quote them when
they are not delimiting.
However, there are times when a method fails unexpectedly and may
require the use of Quote to work. Should this happen, you can probably
file a bug/enhancement request for Mail::IMAPClient to safeguard the
particular call/case better.
An example is RFC822 Message-id's, which usually don't contain quotes
or parens. When dealing with these it is usually best to take
proactive, defensive measures from the very start and use Quote.
Range
Example:
my $parsed = $imap->parse_headers(
$imap->Range( $imap->messages ), "Date", "Subject"
);
The Range method will condense a list of message sequence numbers or
message UID's into the most compact format supported by RFC3501. It
accepts one or more arguments, each of which can be:
a) a message number,
b) a comma-separated list of message numbers,
c) a colon-separated range of message numbers (i.e. "$begin:$end")
d) a combination of messages and message ranges, separated by commas
(i.e. 1,3,5:8,10), or
e) a reference to an array whose elements are like a) through d).
The Range method returns a Mail::IMAPClient::MessageSet object. The
object uses overload and if treated as a string it will act like 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.
This method provides an easy way to add or remove messages from a
message set.
For more information see Mail::IMAPClient::MessageSet.
Rfc3501_date
Example:
$Rfc3501_date = $imap->Rfc3501_date($seconds);
# or:
$Rfc3501_date = Mail::IMAPClient->Rfc3501_date($seconds);
The Rfc3501_date method accepts one input argument, a number of seconds
since the epoch date. It returns an RFC3501 compliant date string for
that date (as required in date-related arguments to SEARCH, such as
"since", "before", etc.).
Rfc3501_datetime
Example:
$date = $imap->Rfc3501_datetime($seconds);
# or:
$date = Mail::IMAPClient->Rfc3501_datetime($seconds);
The Rfc3501_datetime method accepts one or two arguments: a obligatory
timestamp and an optional zone. The zone shall be formatted as
"[+-]\d{4}", and defaults to +0000. The timestamp follows the
definition of the output of the platforms specific "time", usually in
seconds since Jan 1st 1970. However, you have to correct the number
yourself for the zone.
Rfc822_date
Example:
$Rfc822_date = $imap->Rfc822_date($seconds);
# or:
$Rfc822_date = Mail::IMAPClient->Rfc822_date($seconds);
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
message strings before calling "append", "search", etc.
Strip_cr
Examples:
my $stripped = $imap->Strip_cr($string);
# or:
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);
The Strip_cr method strips carriage returns from input and returns the
new string to the caller. 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.
NOTE: Strip_cr does not remove new line characters.
OBJECT METHODS
Object methods must be invoked against objects created via the "new"
method and cannot be invoked as class methods.
There object methods typically fall into one of two categories. There
are 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 object control methods 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 "Transaction", "Status", and "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 "undef" on failure
and something besides "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 "LastError" or $@, 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 Mail::IMAPClient
methods. Patches are welcome. In the pre-2.99 releases of this
module, they were automatically created (AUTOLOAD), but that was very
error-prone and stalled the progress of this module.
Mailbox Control Methods
append
Example:
my $uid_or_true = $imap->append( $folder, $msgtext )
or die "Could not append: ", $imap->LastError;
WARNING: This method may be deprecated in the future, consider using
"append_string" instead of this method.
The append method adds a message to the specified folder. See
"append_string" for details as it is effectively an alias for that
method.
DEPRECATED BEHAVIOR: Additional arguments are added to the message
text, separated with <CR><LF>.
append_string
Example:
# brackets indicate optional arguments (not array refs):
my $uidort = $imap->append_string( $folder, $msgtext [,$flags [,$date ] ] )
or die "Could not append_string: ", $imap->LastError;
Arguments:
$folder
the name of the folder to append the message to
$msgtext
the message text (including headers) of the message
$flags
An optional list of flags to set. The list must be specified as a
space-separated list of flags, including any backslashes that may
be necessary and optionally enclosed by parenthesis.
$date
An optional RFC3501 date argument to set as the internal date. It
should be in the format described for date_time fields in RFC3501,
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 undef as the third ($flags) argument.
Returns:
error: undef
On error, undef can be returned regardless of LIST/SCALAR context.
Check "LastError" for details.
success: UID or $imap
With UIDPLUS the UID of the new message is returned otherwise a
true value (currently $self) is returned.
To protect against "bare newlines", append will insert a carriage
return before any newline that is "bare".
append_file
Example:
my $new_msg_uid = $imap->append_file(
$folder,
$file,
[ undef, $flags, $date ] # optional
) or die "Could not append_file: ", $imap->LastError;
The append_file method adds a message to the specified folder. Note:
The brackets in the example indicate optional arguments; they do not
mean that the argument should be an array reference.
Arguments:
$folder
the name of the folder to append the message to
$file
a filename, filehandle or SCALAR reference which holds an
RFC822-formatted message
undef
a deprecated argument used as a place holder for backwards
compatibility
$flags
The optional argument is handled the same as append_string.
$date
The optional argument is handled the same as append_string (RFC3501
date), with the exception that if $date is "1" (one) then the
modification time (mtime) of the file will be used.
Returns:
error: undef
On error, undef can be returned regardless of LIST/SCALAR context.
Check "LastError" for details.
success: UID or $imap
With UIDPLUS the UID of the new message is returned otherwise a
true value (currently $self) is returned.
To protect against "bare newlines", append_file will insert a carriage
return before any newline that is "bare".
The append_file method provides a mechanism for allowing large messages
to be appended without holding the whole file in memory.
Version note: In 2.x an optional third argument to use for
"input_record_separator" was allowed, however this argument is
ignored/not supported as of 3.x.
authenticate
Example:
$imap->authenticate( $authentication_mechanism, $coderef )
or die "Could not authenticate: ", $imap->LastError;
This method implements the AUTHENTICATE IMAP client command. It can be
called directly or may be called by "login" if the "Authmechanism"
parameter is set to anything except 'LOGIN'.
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 method 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 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><LF> sequence is appended if necessary.
If one or both of the arguments are not specified in the call to
authenticate but their corresponding parameters have been set
("Authmechanism" and "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
"Authcallback" parameter, then the first argument must be one of the
authentication mechanisms for which Mail::IMAPClient has built in
support.
See also the "login" method, which is the simplest form of
authentication defined by RFC3501.
before
Example:
my @msgs = $imap->before($Rfc3501_date)
or warn "No messages found before $Rfc3501_date.\n";
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
Example:
my $string = $imap->body_string($msgId)
or die "Could not body_string: ", $imap->LastError;
The body_string method accepts a message sequence number (or a message
UID, if the "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.
bodypart_string
Example:
my $string = $imap->bodypart_string(
$msgid, $part_number, $length, $offset
) or die "Could not get bodypart string: ", $imap->LastError;
The bodypart_string method accepts a message sequence number (or a
message UID, if the "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.
bodypart_string will return "undef" if it encounters an error.
capability
Example:
my $features = $imap->capability
or die "Could not determine capability: ", $imap->LastError;
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". Supported capabilities are cached by the client,
however, this cache is deleted after a connection is set to
Authenticated and when "starttls" is called.
See also "has_capability".
close
Example:
$imap->close or die "Could not close: $@\n";
The close method is used to close the currently selected folder via the
CLOSE IMAP client command. According to RFC3501, the CLOSE command
performs an implicit EXPUNGE, which means that any messages that are
flagged as \Deleted (i.e. with the "delete_message" method) will now be
deleted. If you haven't deleted any messages then close can be thought
of as an "unselect".
Note: this closes the currently selected folder, not the IMAP session.
See also "delete_message", "expunge", and RFC3501.
compress
Example:
$imap->compress or die "Could not enable RFC4978 compression: $@\n";
The compress method accepts no arguments. This method is used to
instruct the server to use the DEFLATE (RFC1951) compression extension.
See the "Compress" attribute for how to specify arguments for use
during the the initialization process.
Version note: method added in Mail::IMAPClient 3.30
connect
Example:
$imap->connect or die "Could not connect: $@\n";
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.
When the parameter is an absolute file path, an UNIX socket will get
opened. 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. It returns "undef" on failure.
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 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 currently selected
folder. Those messages will be copied into the folder named in the
first argument.
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.
create
Example:
$imap->create($new_folder)
or die "Could not create $new_folder: $@\n";
The create method accepts one argument, the name of a folder (or what
RFC3501 calls a "mailbox") to create. If you specify additional
arguments to the 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 specify additional arguments to the 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.
create returns a true value on success and "undef" on failure.
date
Example:
my $date = $imap->date($msg);
The date method accepts one argument, a message sequence number (or a
message UID if the "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 date method is a short-cut for:
my $date = $imap->get_header($msg,"Date");
delete
Example:
$imap->delete($folder) or die "Could not delete $folder: $@\n";
The delete method accepts a single argument, the name of a folder to
delete. It returns a true value on success and "undef" on failure.
deleteacl
Example:
$imap->deleteacl( $folder, $userid )
or die "Could not delete acl: $@\n";
The deleteacl method accepts two input arguments, a folder name, a user
id (or authentication identifier, to use the terminology of RFC2086).
See RFC2086 for more information. (This is somewhat experimental and
its implementation may change.)
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 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. If successful, 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 for every message. In this
manner the 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 delete_message will return "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 mileage may vary' and all
that.)
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 with this requirement
will almost certainly result in the wrong message(s) being deleted.
ADDITIONAL NOTE: 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). Or at least "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 "expunge" or "close".
See also: the "delete" method, to delete a folder, the "expunge"
method, to expunge a folder, the "restore_message" method to undelete a
message, and the "close" method (implemented here via the default
method) to close a folder. Oh, and don't forget about RFC3501.
deny_seeing
Example:
# Reset all read msgs to unread
# (produces error if there are no seen msgs):
$imap->deny_seeing( scalar($imap->seen) )
or die "Could not deny_seeing: $@\n";
The deny_seeing method accepts a list of one or more message sequence
numbers, or a single reference to an array of one or more message
sequence numbers, as its argument(s). It then unsets the "\Seen" flag
for those messages (so that you can "deny" that you ever saw them). Of
course, if the "Uid" parameter is set to a true value then those
message sequence numbers should be unique message id's.
Note that specifying "$imap->deny_seeing(@msgs)" is just a shortcut for
specifying "$imap->unset_flag("Seen",@msgs)".
disconnect
Example:
$imap->disconnect or warn "Could not logout: $@\n";
This method calls "logout", see "logout" for details.
done
Example:
my $tag = $imap->idle or warn "idle failed: $@\n";
doSomethingA();
my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
doSomethingB();
my $results = $imap->done($tag) or warn "Error from done: $@\n";
The done method tells the IMAP server to terminate the IDLE command.
The only argument is the tag (identifier) received from the previous
call to "idle". If tag is not specified a default tag based on the
Count attribute is assumed to be the tag to look for in the response
from the server.
If an invalid tag is specified, or the default tag is wrong, then done
will hang indefinitely or until a timeout occurs.
If done is called when an "idle" command is not active then the server
will likely respond with an error like * BAD Invalid tag.
On failure <undef> is returned and "LastError" is set.
See also "idle", "idle_data" and "Results".
examine
Example:
$imap->examine($folder) or die "Could not examine: $@\n";
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
Example:
$imap->exists($folder) or warn "$folder not found: $@\n";
Accepts one argument, a folder name. Returns true if the folder exists
or false if it does not exist.
expunge
Example:
$imap->expunge($folder) or die "Could not expunge: $@\n";
The expunge method accepts one optional argument, a folder name. It
expunges the folder specified as the argument, or the currently
selected folder (if any) when no argument is supplied.
Although RFC3501 does not permit optional arguments (like a folder
name) to the EXPUNGE client command, the "expunge" method does. Note:
expunging a folder deletes the messages that have the \Deleted flag set
(i.e. messages flagged via "delete_message").
See also the "close" method, which "deselects" as well as expunges.
fetch
Usage:
$imap->fetch( [$seq_set|ALL], @msg_data_items )
Example:
my $output = $imap->fetch(@args) or die "Could not fetch: $@\n";
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 RFC3501.)
If called in array context, fetch will return an array of output lines.
The output lines will be returned just as they were received from the
server, so your script will have to be prepared to parse out the bits
you want. The only exception to this is literal strings, which will be
inserted into the output line at the point at which they were
encountered (without the {nnn} literal field indicator). See RFC3501
for a description of literal fields.
If fetch is called in a scalar context, then a reference to an array
(as described above) is returned instead of the entire array.
fetch returns "undef" on failure. Inspect "LastError" or $@ for an
explanation of your error.
fetch_hash
Usage:
$imap->fetch_hash( [$seq_set|ALL], @msg_data_items, [\%msg_by_ids] )
Example:
my $hashref = {};
$imap->fetch_hash( "RFC822.SIZE", $hashref );
print "Msg #$m is $hashref->{$m} bytes\n" foreach my $m (keys %$hashref);
The fetch_hash method accepts a list of message attributes to be
fetched (as described in RFC3501). It returns a hash whose keys are
all the messages in the currently selected folder and whose values are
key-value pairs of fetch keywords and the message's value for that
keyword (see sample output below).
If fetch_hash is called in scalar context, it returns a reference to
the hash instead of the hash itself. If the last argument is a hash
reference, then that hash reference will be used as the place where
results are stored (and that reference will be returned upon successful
completion). If the last argument is not a reference then it will be
treated as one of the FETCH attributes and a new hash will be created
and returned (either by value or by reference, depending on the context
in which fetch_hash was called).
For example, if you have a folder with 3 messages and want the size and
internal date for each of them, you could do the following:
use Mail::IMAPClient;
use Data::Dumper;
# ... other code goes here
$imap->select($folder);
my $hash = $imap->fetch_hash("RFC822.SIZE","INTERNALDATE");
# (Same as:
# my $hash = $imap->fetch_hash("RFC822.SIZE");
# $imap->fetch_hash("INTERNALDATE",$hash);
# ).
print Data::Dumper->Dumpxs([$hash],['$hash']);
This would result in Data::Dumper output similar to the following:
$hash = {
'1' => {
'INTERNALDATE' => '21-Sep-2002 18:21:56 +0000',
'RFC822.SIZE' => '1586',
},
'2' => {
'INTERNALDATE' => '22-Sep-2002 11:29:42 +0000',
'RFC822.SIZE' => '1945',
},
'3' => {
'INTERNALDATE' => '23-Sep-2002 09:16:51 +0000',
'RFC822.SIZE' => '134314',
}
};
By itself this method may be useful for tasks like obtaining the size
of every message in a folder. It issues one command and receives one
(possibly long!) response from the server.
If the fetch request causes the server to return data in a
parenthesized list, the data within the parenthesized list may be
escaped via the Escape() method. Use the Unescape() method to get the
raw values back in this case.
flags
Example:
my @flags = $imap->flags($msgid)
or die "Could not flags: $@\n";
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.
As of version 1.11, you can supply either a list of message id's or a
reference to an array of of message id's (which means either sequence
number, if the Uid parameter is false, or message UID's, if the Uid
parameter is true) instead of supplying a single message sequence
number or UID. If you do, then the return value will not be an array
or array reference; instead, it will be a hash reference, with each key
being a message sequence number (or UID) and each value being a
reference to an array of flags set for that message.
For example, if you want to display the flags for every message in the
folder where you store e-mail related to your plans for world
domination, you could do something like this:
use Mail::IMAPClient;
my $imap = Mail::IMAPClient->new(
Server => $imaphost,
User => $login,
Password => $pass,
Uid => 1, # optional
);
$imap->select("World Domination");
# get the flags for every message in my 'World Domination' folder
$flaghash = $imap->flags( scalar( $imap->search("ALL") ) );
# pump through sorted hash keys to print results:
for my $k (sort { $flaghash->{$a} <=> $flaghash->{$b} } keys %$flaghash) {
# print: Message 1: \Flag1, \Flag2, \Flag3
print "Message $k:\t",join(", ",@{$flaghash->{$k}}),"\n";
}
folders
Example:
$imap->folders or die "Could not list folders: $@\n";
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.
The folders argument accepts one optional argument, which is a prefix.
If a prefix is supplied to the folders method, then only folders
beginning with the prefix will be returned.
For example:
print join(", ",$imap->folders),".\n";
# Prints:
# INBOX, Sent, Projects, Projects/Completed, Projects/Ongoing, Projects Software.
print join(", ",$imap->folders("Projects"),".\n";
# Prints:
# Projects, Projects/Completed, Projects/Ongoing, Projects Software.
print join(", ",$imap->folders("Projects" . $imap->separator),".\n";
# Prints:
# Projects/Completed, Projects/Ongoing
Please note that documentation previously suggested that if you just
want to list a folder's subfolders (and not the folder itself), then
you need to include the hierarchy separator character (as returned by
the "separator" method). However, this does not match the behavior of
the existing implementation, so you will need to manually exclude the
parent folder from the results.
xlist_folders
Example:
my $xlist = $imap->xlist_folders
or die "Could not get xlist folders.\n";
IMAP servers implementing the XLIST extension (such as Gmail) designate
particular folders to be used for particular functions. This is useful
in the case where you want to know which folder should be used for
Trash when the actual folder name can't be predicted (e.g. in the case
of Gmail, the folder names change depending on the user's locale
settings).
The xlist_folders method returns a hash listing any "xlist" folder
names, with the values listing the actual folders that should be used
for those names. For example, using this method with a Gmail user
using the English (US) locale might give this output from Data::Dumper:
$VAR1 = {
'Inbox' => 'Inbox',
'AllMail' => '[Gmail]/All Mail',
'Trash' => '[Gmail]/Trash',
'Drafts' => '[Gmail]/Drafts',
'Sent' => '[Gmail]/Sent Mail',
'Spam' => '[Gmail]/Spam',
'Starred' => '[Gmail]/Starred'
};
The same list for a user using the French locale might look like this:
$VAR1 = {
'Inbox' => 'Bo&AO4-te de r&AOk-ception',
'AllMail' => '[Gmail]/Tous les messages',
'Trash' => '[Gmail]/Corbeille',
'Drafts' => '[Gmail]/Brouillons',
'Sent' => '[Gmail]/Messages envoy&AOk-s',
'Spam' => '[Gmail]/Spam',
'Starred' => '[Gmail]/Suivis'
};
Mail::IMAPClient recognizes the following "xlist" folder names:
Inbox
AllMail
Trash
Drafts
Sent
Spam
Starred
These are currently the only ones supported by Gmail. The XLIST
extension is not documented, and there are no other known
implementations other than Gmail, so this list is based on what Gmail
provides.
If the server does not support the XLIST extension, this method returns
undef.
Version note: method added in Mail::IMAPClient 3.21
has_capability
Example:
my $has_feature = $imap->has_capability($feature)
or die "Could not do has_capability($feature): $@\n";
Returns true if the IMAP server to which the IMAPClient object is
connected has the capability specified as an argument to
has_capability. If the server does not have the capability then the
empty string "" is returned, if the underlying "capability" calls fails
then undef is returned.
idle
Example:
my $tag = $imap->idle or warn "idle failed: $@\n";
doSomethingA();
my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
doSomethingB();
my $results = $imap->done($tag) or warn "Error from done: $@\n";
The idle method tells the IMAP server the client is ready to accept
unsolicited mailbox update messages. This method is only valid on
servers that support the IMAP IDLE extension, see RFC2177 for details.
The idle method accepts no arguments and returns the tag (identifier)
that was sent by the client for this command. This tag should be
supplied as the argument to "done" when ending the IDLE command.
On failure <undef> is returned and "LastError" is set.
The method "idle_data" may be used once idle has been successful.
However, no mailbox operations may be called until the idle command has
been terminated by calling "done". Failure to do so will result in an
error and the idle command will typically be terminated by the server.
See also "idle_data" and "done".
idle_data
Usage:
# an optional timeout in seconds may be specified
$imap->idle_data( [$timeout] )
Example:
my $tag = $imap->idle or warn "idle failed: $@\n";
doSomethingA();
my $idlemsgs = $imap->idle_data() or warn "idle_data error: $@\n";
doSomethingB();
my $results = $imap->done($tag) or warn "Error from done: $@\n";
The idle_data method can be used to accept any unsolicited mailbox
update messages that have been sent by the server during an "idle"
command. This method does not send any commands to the server, it
simply looks for and optionally waits for data from the server and
returns that data to the caller.
The idle_data method accepts an optional $timeout argument and returns
an array (or an array reference if called in scalar context) with the
messages from the server.
By default a timeout of 0 seconds is used (do not block). Internally
the timeout is passed to "select" in perlfunc. The timeout controls
how long the select call blocks if there are no messages waiting to be
read from the server.
On failure <undef> is returned and "LastError" is set.
See also "imap" and "done".
Version note: method added in Mail::IMAPClient 3.23 Warning: this
method is considered experimental and the interface/output may change
in a future version.
imap4rev1
Example:
$imap->imap4rev1 or die "Could not imap4rev1: $@\n";
Returns true if the IMAP server to which the IMAPClient object is
connected has the IMAP4REV1 capability. If the server does not have
the capability then the empty string "" is returned, if the underlying
"capability" calls fails then undef is returned.
internaldate
Example:
my $msg_internal_date = $imap->internaldate($msgid)
or die "Could not internaldate: $@\n";
internaldate accepts one argument, a message id (or UID if the "Uid"
parameter is true), and returns that message's internal date or undef
if the call fails or internal date is not returned.
get_bodystructure
Example:
my $bodyStructObject = $imap->get_bodystructure($msgid)
or die "Could not get_bodystructure: $@\n";
The get_bodystructure method accepts one argument, a message sequence
number or, if "Uid" is true, a message UID. It obtains the message's
body structure and returns a parsed Mail::IMAPClient::BodyStructure
object for the message.
get_envelope
Example:
my $envObject = $imap->get_envelope(@args)
or die "Could not get_envelope: $@\n";
The get_envelope method accepts one argument, a message sequence number
or, if "Uid" is true, a message UID. It obtains the message's envelope
and returns a Mail::IMAPClient::BodyStructure::Envelope object for the
envelope, which is just a version of the envelope that's been parsed
into a Perl object.
For more information on how to use this object once you've gotten it,
see the Mail::IMAPClient::BodyStructure documention. (As of this
writing there is no separate pod document for
Mail::IMAPClient::BodyStructure::Envelope.)
getacl
Example:
my $hash = $imap->getacl($folder)
or die "Could not getacl for $folder: $@\n";
getacl accepts one argument, the name of a folder. If no argument is
provided then the currently selected folder is used as the default. It
returns a reference to a hash. The keys of the hash are userids that
have access to the folder, and the value of each element are the
permissions for that user. The permissions are listed in a string in
the order returned from the server with no white space or punctuation
between them.
get_header
Example:
my $messageId = $imap->get_header( $msg, "Message-Id" );
The get_header method accepts two arguments, a message sequence number
or UID and the name of an RFC822 header (without the trailing colon).
It returns the value for that header in the message whose sequence
number or UID was passed as the first argument. If no value can be
found it returns "undef"; if multiple values are found it returns the
first one. Its return value is always a scalar. get_header uses case
insensitive matching to get the value, so you do not have to worry
about the case of your second argument.
The get_header method is a short-cut for:
my $messageId = $imap->parse_headers($msg,"Subject")->{"Subject"}[0];
getquotaroot
Example:
my $results = $imap->getquotaroot($mailboxname)
or die "Could not getquotaroot for $mailboxname: $@\n";
The getquotaroot method implements the RFC2087 GETQUOTAROOT command.
The "$mailboxname" defaults to "INBOX" if no argument is provided.
On error "undef" is returned, otherwise "Results" are returned. The
results should have the untagged QUOTAROOT response from the server
along with the QUOTAROOT's resource usage and limits in an untagged
QUOTA response.
See also RFC2087, "getquota", "setquota", "quota" and "quota_usage".
getquota
Example:
my $results = $imap->getquota($quotaroot)
or die "Could not getquota for $quotaroot: $@\n";
The getquota method implements the RFC2087 GETQUOTA command. The
"$quotaroot" defaults to "user/User" if no argument is provided.
On error "undef" is returned, otherwise "Results" are returned. The
results from the server should have the untagged QUOTA response from
the server.
See also RFC2087, "getquotaroot", "quota" and "quota_usage".
quota
Example:
my $limit = $imap->quota($quotaroot)
or die "Could not get quota limit for $quotaroot: $@\n";
The quota method takes the "Results" from getquota and parses out the
"STORAGE" limit returned by the server. The "$quotaroot" defaults to
"INBOX" if no argument is provided.
On error "undef" is returned, otherwise the integer "STORAGE" limit
provided by the server is returned.
See also RFC2087, "getquotaroot", "getquota" and "quota_usage".
quota_usage
Example:
my $usage = $imap->quota_usage($quotaroot)
or die "Could not get quota usage for $quotaroot: $@\n";
The quota_usage method takes the "Results" from getquota and parses out
the "STORAGE" usage returned by the server. The "$quotaroot" defaults
to "INBOX" if no argument is provided.
On error "undef" is returned, otherwise the integer "STORAGE" usage
provided by the server is returned.
See also RFC2087, "getquotaroot", "getquota" and "quota".
setquota
Example:
my $results = $imap->setquota( $quotaroot, $resource, $limit )
or die "Could not setquota for $quotaroot: $@\n";
The setquota method implements the RFC2087 SETQUOTA command. It
accepts multiple pairs of $resource and $limit arguments. The
"$quotaroot" defaults to "user/User" if not defined.
On error "undef" is returned, otherwise "Results" are returned.
See also RFC2087, "getquotaroot" and "getquota".
is_parent
Example:
my $hasKids = $imap->is_parent($folder);
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
Example:
my @raw_output = $imap->list(@args)
or die "Could not list: $@\n";
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 unadulterated output of the LIST
command. (If you want your output adulterated then see the "folders"
method, above.)
An "undef" value is returned in case of errors. Be sure to check for
it.
listrights
Example:
$imap->listrights($folder,$user)
or die "Could not listrights: $@\n";
The listrights method implements the IMAP LISTRIGHTS client command
(RFC2086). It accepts two arguments, the foldername and a user id. It
returns the rights the specified user has for the specified folder. If
called in a scalar context then the rights are returned a strings, with
no punctuation or white space or any nonsense like that. If called in
array context then listrights returns an array in which each element is
one right.
login
Example:
$imap->login or die "Could not login: $@\n";
The login method implements the IMAP LOGIN client command to log into
the server. It automatically calls "authenticate" if the Authmechanism
parameter is set to anything except 'LOGIN' otherwise a clear text
LOGIN is attempted.
The User and Password parameters must be set before the login method
can be invoked. On success, a Mail::IMAPClient object with the Status
of Authenticated is returned. On failure, undef is returned and $@ is
set. The methods "new", "connect", and "Socket" may automatically
invoke login see the documentation of each method for details.
If the "Compress" parameter is set, the "compress" method will
automatically be called after successful authentication.
See also "proxyauth" and "Proxy" for additional information regarding
ways of authenticating with a server via SASL and/or PROXYAUTH.
proxyauth
Example:
$imap->login("admin", "password");
$imap->proxyauth("someuser");
The proxyauth method implements the IMAP PROXYAUTH client command. The
command is used by Sun/iPlanet/Netscape IMAP servers to allow an
administrative user to masquerade as another user.
logout
Example:
$imap->logout or die "Could not logout: $@\n";
The logout method implements the LOGOUT IMAP client commmand. This
method causes the server to end the connection and the IMAPClient
client enters the Unconnected state. This method does not, destroy the
IMAPClient object, thus the "connect" and "login" methods can be used
to establish a new IMAP session.
Note that RFC2683 section 3.1.2 (Severed connections) makes some
recommendations on how IMAP clients should behave. It is up to the
user of this module to decide on the preferred behavior and code
accordingly.
Version note: documentation (from 2.x through 3.23) claimed that
Mail::IMAPClient would attempt to log out of the server during DESTROY
if the object is in the "Connected" state. This documentation was
apparently incorrect from at least 2.2.2 and possibly earlier versions
on up.
lsub
Example:
$imap->lsub(@args) or die "Could not lsub: $@\n";
The lsub method implements the IMAP LSUB 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 lsub command
"tag LSUB "" '*'" is issued.
The lsub method returns an array (or an array reference, if called in a
scalar context). The array is the unaltered output of the LSUB
command. If you want an array of subscribed folders then see the
"subscribed" method, below.
mark
Example:
$imap->mark(@msgs) or die "Could not mark: $@\n";
The mark method accepts a list of one or more messages sequence
numbers, or a single reference to an array of one or more message
sequence numbers, as its argument(s). It then sets the "\Flagged" flag
for those message(s). Of course, if the "Uid" parameter is set to a
true value then those message sequence numbers had better be unique
message id's.
Note that specifying "$imap->see(@msgs)" is just a shortcut for
specifying "$imap->set_flag("Flagged",@msgs)".
Massage
Example:
$imap->search(HEADER => 'Message-id' => $imap->Massage($msg_id,1));
The Massage method accepts a value as an argument and, optionally, a
second value that, when true, indicates that the first argument is not
the name of an existing folder.
It returns its argument as a correctly quoted string or a literal
string.
Note that you should rarely use this on folder names, since methods
that accept folder names as an argument will call Massage for you. In
fact, it was originally developed as an undocumented helper method
meant for internal Mail::IMAPClient methods only.
You may also want to see the "Quote" method, which is related to this
method.
message_count
Example:
my $msgcount = $imap->message_count($folder);
defined($msgcount) or die "Could not message_count: $@\n";
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. If you don't supply an argument to
message_count then it will return the number of messages in the
currently selected folder (assuming of course that you've used the
"select" or "examine" method to select it instead of trying something
funky). Note that RFC2683 contains warnings about the use of the IMAP
STATUS command (and thus the "status" method and therefore the
message_count method) against the currently selected folder. You
should carefully consider this before using message_count on the
currently selected folder. You may be better off using "search" or one
of its variants (especially "messages"), and then counting the results.
On the other hand, I regularly violate this rule on my server without
suffering any dire consequences. Your mileage may vary.
message_string
Example:
my $string = $imap->message_string($msgid)
or die "Could not message_string: $@\n";
The message_string method accepts a message sequence number (or message
UID if "Uid" is true) as an argument and returns the message as a
string. The returned value contains the entire message in one scalar
variable, including the message headers. Note that using this method
will set the message's "\Seen" flag as a side effect, unless Peek is
set to a true value.
message_to_file
Example:
$imap->message_to_file($file,@msgs)
or die "Could not message_to_file: $@\n";
The message_to_file method accepts a filename or file handle and one or
more message sequence numbers (or message UIDs if "Uid" is true) as
arguments and places the message string(s) (including RFC822 headers)
into the file named in the first argument (or prints them to the file
handle, if a file handle is passed). The returned value is true on
success and "undef" on failure.
If the first argument is a reference, it is assumed to be an open file
handle and will not be closed when the method completes, If it is a
file, it is opened in append mode, written to, then closed.
Note that using this method will set the message's "\Seen" flag as a
side effect. But you can use the "deny_seeing" method to set it back,
or set the "Peek" parameter to a true value to prevent setting the
"\Seen" flag at all.
This method currently works by making some basic assumptions about the
server's behavior, notably that the message text will be returned as a
literal string but that nothing else will be. If you have a better
idea then I'd like to hear it.
message_uid
Example:
my $msg_uid = $imap->message_uid($msg_seq_no)
or die "Could not get uid for $msg_seq_no: $@\n";
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.
messages
Example:
# Get a list of messages in the current folder:
my @msgs = $imap->messages or die "Could not messages: $@\n";
# Get a reference to an array of messages in the current folder:
my $msgs = $imap->messages or die "Could not messages: $@\n";
If called in list context, the messages method returns a list of all
the messages in the currently selected folder. If called in scalar
context, it returns a reference to an array containing all the messages
in the folder. If you have the "Uid" parameter turned off, then this
is the same as specifying "1 ... $imap->message_count"; if you have UID
set to true then this is the same as specifying
"$imap->"search"("ALL")".
migrate
Example:
$imap_src->migrate( $imap_dest, "ALL", $targetFolder )
or die "Could not migrate: ", $imap_src->LastError;
The migrate method copies the indicated message(s) from the currently
selected folder to another Mail::IMAPClient object's session. It
requires these arguments:
1. a reference to the target Mail::IMAPClient object (not the calling
object, which is connected to the source account);
2. the message(s) to be copied, specified as either a) the message
sequence number (or message UID if the UID parameter is true) of a
single message, b) a reference to an array of message sequence
numbers (or message UID's if the UID parameter is true) or c) the
special string "ALL", which is a shortcut for the results of
""search"("ALL")".
3. the name of the destination folder on the target mailbox to receive
the message(s). If this argument is not supplied or is undef then
the currently selected folder on the calling object will be used.
The destination folder will be automatically created if necessary.
The target ($imap_dest) Mail::IMAPClient object must not be the same
object as the source ($imap_src).
This method does not attempt to minimize memory usage. In the future
it could be enhanced to (optionaly) write message data to a temporary
file to avoid storing the entire message in memory.
To work around potential network timeouts on large messages, consider
setting "Reconnectretry" to 1 on both $imap_src and $imap_dest.
See also "Supportedflags".
move
Example:
my $newUid = $imap->move($newFolder, $oldUid)
or die "Could not move: $@\n";
$imap->expunge;
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 successful, 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 comma-separated
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".
Note that a move really just involves copying the message to the new
folder and then setting the \Deleted flag. To actually delete the
original message you will need to run "expunge" (or "close").
namespace
Example:
my $refs = $imap->namespace
or die "Could not namespace: $@\n";
The namespace method runs the NAMESPACE IMAP command (as defined in RFC
2342). When called in a list context, it returns a list of three
references. Each reference looks like this:
[
[ $prefix_1, $separator_1 ],
[ $prefix_2, $separator_2 ],
[ $prefix_n, $separator_n ],
]
The first reference provides a list of prefixes and separator
characters for the available personal namespaces. The second reference
provides a list of prefixes and separator characters for the available
shared namespaces. The third reference provides a list of prefixes and
separator characters for the available public namespaces.
If any of the three namespaces are unavailable on the current server
then an 'undef' is returned instead of a reference. So for example if
shared folders were not supported on the server but personal and public
namespaces were both available (with one namespace each), the returned
value might resemble this:
[ [ "", "/" ] , undef, [ "#news", "." ] ];
If the namespace method is called in scalar context, it returns a
reference to the above-mentioned list of three references, thus
creating a single structure that would pretty-print something like
this:
$VAR1 = [
[
[ $user_prefix_1, $user_separator_1 ],
[ $user_prefix_2, $user_separator_2 ],
[ $user_prefix_n, $user_separator_n ],
], # or undef
[
[ $shared_prefix_1, $shared_separator_1 ],
[ $shared_prefix_2, $shared_separator_2 ],
[ $shared_prefix_n, $shared_separator_n ],
], # or undef
[
[ $public_prefix_1, $public_separator_1 ],
[ $public_prefix_2, $public_separator_2 ],
[ $public_prefix_n, $public_separator_n ],
], # or undef
];
on
Example:
my @msgs = $imap->on($Rfc3501_date)
or warn "Could not find messages sent on $Rfc3501_date: $@\n";
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.
parse_headers
Example:
my $hashref = $imap->parse_headers($msg||\@msgs, "Date", "Subject")
or die "Could not parse_headers: $@\n";
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 formatted 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. Also, in the
case of headers whose contents are also reflected in the envelope, you
can use the "get_envelope" method as an alternative to "parse_headers".
If the "Uid" parameter is true then the first argument will be treated
as a message UID. If the first argument is a reference to an array of
message sequence numbers (or UID's if "Uid" is true), then
parse_headers will be run against each message in the array. In this
case the return value is a hash, in which the key is the message
sequence number (or UID) and the value is a reference to a hash as
described above.
An example of using parse_headers to print the date and subject of
every message in your smut folder could look like this:
use Mail::IMAPClient;
my $imap = Mail::IMAPClient->new(
Server => $imaphost, User => $login, Password => $pass, Uid => 1
);
$imap->select("demo");
my $msgs = $imap->search("ALL");
for my $h (
# get the Subject and Date from every message in folder "demo" the
# first arg is a reference to an array listing all messages in the
# folder (which is what gets returned by the $imap->search("ALL")
# method when called in scalar context) and the remaining arguments
# are the fields to parse out The key is the message number, which
# in this case we don't care about:
values %{ $imap->parse_headers( $msgs , "Subject", "Date") } )
{
# $h is the value of each element in the hash ref returned
# from parse_headers, and $h is also a reference to a hash.
# We'll only print the first occurrence of each field because
# we don't expect more than one Date: or Subject: line per
# message.
print map { "$_:\t$h->{$_}[0]\n"} keys %$h;
}
recent
Example:
my @recent = $imap->recent or warn "No recent msgs: $@\n";
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
Example:
my $count = 0;
defined($count = $imap->recent_count($folder))
or die "Could not recent_count: $@\n";
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).
reconnect
Example:
$imap->noop or $imap->reconnect or die "noop failed: $@\n";
Attempt to reconnect if the IMAP connection unless $imap is already in
the IsConnected state. This method calls "connect" and optionally
"select" if a Folder was previously selected. On success, returns the
(same) $imap object. On failure <undef> is returned and "LastError" is
set.
Version note: method added in Mail::IMAPClient 3.17
rename
Example:
$imap->rename($oldname,$nedwname)
or die "Could not rename: $@\n";
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.
restore_message
Example:
$imap->restore_message(@msgs) or die "Could not restore_message: $@\n";
The restore_message method is used to undo a previous "delete_message"
operation (but not if there has been an intervening "expunge" or
"close"). The IMAPClient object must be in "Selected" status to use
the restore_message method.
The restore_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 have
their \Deleted flags cleared, effectively "undeleting" the messages.
restore_message returns the number of messages it was able to restore.
Note that restore_messages is similar to calling
""unset_flag"("\Deleted",@msgs)", except that restore_messages returns
a (slightly) more meaningful value. Also it's easier to type.
run
Example:
$imap->run(@args) or die "Could not run: $@\n";
The run method is provided to make those uncommon things possible...
however, we would like you to contribute the knowledge of missing
features with us.
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 (or arrayref in scalar context) 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.
If you want the control of run but you don't want to worry about tags
then see "tag_and_run", below.
search
Example:
my $msgs1 = $imap->search(@args);
if ($msgs) {
print "search matches: @$msgs1";
}
else {
warn "Error in search: $@\n" if $@;
}
# or note: be sure to quote string properly
my $msgs2 = $imap->search( \( $imap->Quote($msgid), "FROM", q{"me"} ) )
or warn "search failed: $@\n";
# or note: be sure to quote string properly
my $msgs3 = $imap->search('TEXT "string not in mailbox"')
or warn "search failed: $@\n";
The search method implements the SEARCH IMAP client command. Any
arguments supplied to search are prefixed with a space then appended to
the SEARCH IMAP client command. The SEARCH IMAP client command allows
for many options and arguments. See RFC3501 for details.
As of version 3.17 search tries to "DWIM" by automatically quoting
things that likely need quotes when the words do not match any of the
following:
ALL ANSWERED BCC BEFORE BODY CC DELETED DRAFT FLAGGED
FROM HEADER KEYWORD LARGER NEW NOT OLD ON OR RECENT
SEEN SENTBEFORE SENTON SENTSINCE SINCE SMALLER SUBJECT
TEXT TO UID UNANSWERED UNDELETED UNDRAFT UNFLAGGED
UNKEYWORD UNSEEN
The following options exist to avoid the automatic quoting (note:
caller is responsible for verifying the data sent in these cases is
properly escaped/quoted):
· specify a single string/argument in the call to search.
· specify args as scalar references (SCALAR) and the values of those
SCALAR refs will be passed along as-is.
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. If no messages meet
the criteria then search returns an empty list (when in list context)
or "undef" (in scalar context).
Since a valid, successful search can legitimately return zero matches,
you may wish to distinguish between a search that correctly returns
zero hits and a search that has failed for some other reason (i.e.
invalid search parameters). Therefore, the $@ variable will always be
cleared before the SEARCH command is issued to the server, and will
thus remain empty unless the server gives a BAD or NO response to the
SEARCH command.
see
Example:
$imap->see(@msgs) or die "Could not see: $@\n";
The see method accepts a list of one or more messages sequence numbers,
or a single reference to an array of one or more message sequence
numbers, as its argument(s). It then sets the \Seen flag for those
message(s). Of course, if the "Uid" parameter is set to a true value
then those message sequence numbers had better be unique message id's,
but then you already knew that, didn't you?
Note that specifying "$imap->see(@msgs)" is just a shortcut for
specifying "$imap->"set_flag"("Seen",@msgs)".
seen
Example:
my @seenMsgs = $imap->seen or warn "No seen msgs: $@\n";
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 reference to the array
(rather than the array itself) will be returned.
select
Example:
$imap->select($folder) or die "Could not select: $@\n";
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.
selectable
Example:
foreach my $f ( grep( $imap->selectable($_), $imap->folders ) ) {
$imap->select($f);
}
The selectable method accepts one value, a folder name, and returns
true if the folder is selectable or false if it is not selectable.
sentbefore
Example:
my @msgs = $imap->sentbefore($Rfc3501_date)
or warn "Could not find any msgs sent before $Rfc3501_date: $@\n";
The sentbefore method works just like "sentsince", below, except it
searches for messages that were sent before the date supplied as an
argument to the method.
senton
Example:
my @msgs = $imap->senton($Rfc3501_date)
or warn "Could not find any messages sent on $Rfc3501_date: $@\n";
The senton method 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
Example:
my @msgs = $imap->sentsince($Rfc3501_date)
or warn "Could not find any messages sent since $Rfc3501_date: $@\n";
The sentsince method accepts one argument, a date in either epoch time
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 RFC3501 (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 sentsince date. (Actually, it the
server that uses the Date: header; this documentation just assumes that
the date is coming from the Date: header because that's what RFC3501
dictates.)
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. On the other hand, the only thing I check for in a
date_text argument is that it matches the pattern
"/\d\d-\D\D\D-\d\d\d\d/" (notice the lack of anchors), so if your
server lets you add something extra to a date_text string then so will
Mail::IMAPClient.
If you'd like, you can use the "Rfc3501_date" method to convert from
epoch time (as returned by time) into an RFC3501 date specification.
separator
Example:
my $sepChar = $imap->separator(@args)
or die "Could not get separator: $@\n";
The separator method returns the character used as a separator
character in folder hierarchies. On UNIX-based servers, this is often
but not necessarily 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.
If you want your programs to be portable from IMAP server brand X to
IMAP server brand Y, then you should never use hard-coded separator
characters to specify subfolders. (In fact, it's even more complicated
than that, since some server don't allow any subfolders at all, some
only allow subfolders under the "INBOX" folder, and some forbid
subfolders in the inbox but allow them "next" to the inbox.
Furthermore, some server implementations do not allow folders to
contain both subfolders and mail messages; other servers allow this.)
set_flag
Example:
$imap->set_flag( "Seen", @msgs )
or die "Could not set flag: $@\n";
The set_flag method accepts the name of a flag as its first argument
and a list of one or more messages sequence numbers, or a single
reference to an array of one or more message sequence numbers, as its
next argument(s). It then sets the flag specified for those
message(s). Of course, if the "Uid" parameter is set to a true value
then those message sequence numbers had better be unique message id's,
just as you'd expect.
Note that when specifying the flag in question, the preceding backslash
(\) is entirely optional. (For you, that is. Mail::IMAPClient still
has remember to stick it in there before passing the command to the
server if the flag is one of the reserved flags specified in RFC3501.
This is in fact so important that the method checks its argument and
adds the backslash when necessary, which is why you don't have to worry
about it overly much.)
setacl
Example:
$imap->setacl( $folder, $userid, $aclstring )
or die "Could not set acl: $@\n";
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. (This is somewhat experimental and its implementation may
change.)
since
Example:
my @msgs = $imap->since($date)
or warn "Could not find any messages since $date: $@\n";
The since method accepts a date in either epoch format (seconds since
1/1/1970, or as output by "time" in perlfunc and as accepted by
"localtime" in perlfunc) or in the date_text format as defined in
RFC3501 (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.
If since is called in a list context then it will return a list of
messages meeting the SEARCH SINCE criterion, or an empty list if no
messages meet the criterion.
If since is called in a scalar context then it will return a reference
to an array of messages meeting the SEARCH SINCE criterion, or "undef"
if no messages meet the criterion.
Since since is a front-end to "search", some of the same rules apply.
For example, the $@ variable will always be cleared before the SEARCH
command is issued to the server, and will thus remain empty unless the
server gives a BAD or NO response to the SEARCH command.
size
Example:
my $size = $imap->size($msgId)
or die "Could not find size of message $msgId: $@\n";
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.
sort
Example:
my @msgs = $imap->sort(@args);
warn "Error in sort: $@\n" if $@;
The sort method is just like the "search" method, only different. It
implements the SORT extension as described in
http://search.ietf.org/internet-drafts/draft-ietf-imapext-sort-10.txt.
It would be wise to use the "has_capability" method to verify that the
SORT capability is available on your server before trying to use the
sort method. If you forget to check and you're connecting to a server
that doesn't have the SORT capability then sort will return undef.
"LastError" will then say you are "BAD". If your server doesn't
support the SORT capability then you'll have to use "search" and then
sort the results yourself.
The first argument to sort is a space-delimited list of sorting
criteria. The Internet Draft that describes SORT requires that this
list be wrapped in parentheses, even if there is only one sort
criterion. If you forget the parentheses then the sort method will add
them. But you have to forget both of them, or none. This isn't CMS
running under VM!
The second argument is a character set to use for sorting. Different
character sets use different sorting orders, so this argument is
important. Since all servers must support UTF-8 and US-ASCII if they
support the SORT capability at all, you can use one of those if you
don't have some other preferred character set in mind.
The rest of the arguments are searching criteria, just as you would
supply to the "search" method. These are all documented in RFC3501.
If you just want all of the messages in the currently selected folder
returned to you in sorted order, use ALL as your only search criterion.
The sort method returns an array containing sequence numbers of
messages that passed the SORT IMAP client command's search criteria.
If the "Uid" parameter is true then the array will contain message
UID's. If sort is called in scalar context then a pointer to the array
will be passed, instead of the array itself. The message sequence
numbers or unique identifiers are ordered according to the sort
criteria specified. The sort criteria are nested in the order
specified; that is, items are sorted first by the first criterion, and
within the first criterion they are sorted by the second criterion, and
so on.
The sort method will clear $@ before attempting the SORT operation just
as the "search" method does.
starttls
Example:
$imap->starttls() or die "starttls failed: $@\n";
The starttls method accepts no arguments. This method is used to
upgrade an exiting connection which is not authenticated to a TLS/SSL
connection by using the IMAP STARTTLS command followed by using the
start_SSL class method from IO::Socket::SSL to do the necessary TLS
negotiation. The negotiation is done in a blocking fashion with a
default Timeout of 30 seconds. The arguments used in the call to
start_SSL can be controlled by setting the Mail::IMAPClient "Starttls"
attribute to an ARRAY reference containing the desired arguments.
Version note: method added in Mail::IMAPClient 3.22
status
Example:
my @rawdata = $imap->status( $folder, qw/(Messages)/ )
or die "Error obtaining status: $@\n";
The status method accepts one argument, the name of a folder (or
mailbox, to use RFC3501'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).
store
Example:
$imap->store(@args) or die "Could not store: $@\n";
The store method accepts a message sequence number or comma-separated
list of message sequence numbers as a first argument, a message data
item name, and a value for the message data item. Currently, data
items are the word "FLAGS" followed by a space and a list of flags (in
parens). The word "FLAGS" can be modified by prefixing it with either
a "+" or a "-" (to indicate "add these flags" or "remove these flags")
and by suffixing it with ".SILENT" (which reduces the amount of output
from the server; very useful with large message sets). Normally you
won't need to call store because there are oodles of methods that will
invoke store for you with the correct arguments. Furthermore, these
methods are friendlier and more flexible with regards to how you
specify your arguments. See for example "see", "deny_seeing",
"delete_message", and "restore_message". Or "mark", "unmark",
"set_flag", and "unset_flag".
subject
Example:
my $subject = $imap->subject($msg);
The subject method accepts one argument, a message sequence number (or
a message UID, if the Uid parameter is true). The text in the
"Subject" header of that message is returned (without the "Subject: "
prefix). This method is a short-cut for:
my $subject = $imap->get_header($msg, "Subject");
subscribed
Example:
my @subscribedFolders = $imap->subscribed
or warn "Could not find subscribed folders: $@\n";
The subscribed method works like the folders method, above, except that
the returned list (or array reference, if called in scalar context)
contains only the subscribed folders.
Like "folders", you can optionally provide a prefix argument to the
subscribed method.
tag_and_run
Example:
my $output = $imap->tag_and_run(@args)
or die "Could not tag_and_run: $@\n";
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 (without pattern
delimiters). 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).
uidexpunge
Example:
$imap->uidexpunge(@uids) or die "Could not uidexpunge: $@\n";
The uidexpunge method implements the UID EXPUNGE IMAP (RFC4315 UIDPLUS
ext) client command to permanently remove all messages that have the
\Deleted flag set and have a UID that is included in the list of UIDs.
uidexpunge returns an array or arrayref (scalar context) of output
lines returned from the UID EXPUNGE command.
uidexpunge returns undef on failure.
If the server does not support the UIDPLUS extension, this method
returns undef.
uidnext
Example:
my $nextUid = $imap->uidnext($folder) or die "Could not uidnext: $@\n";
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.
thread
Example:
my $thread = $imap->thread($algorithm, $charset, @search_args );
The thread method accepts zero to three arguments. The first argument
is the threading algorithm to use, generally either ORDEREDSUBJECT or
REFERENCES. The second argument is the character set to use, and the
third argument is the set of search arguments to use.
If the algorithm is not supplied, it defaults to REFERENCES if
available, or ORDEREDSUBJECT if available. If neither of these is
available then the thread method returns undef.
If the character set is not specified it will default to UTF-8.
If the search arguments are not specified, the default is ALL.
If thread is called for an object connected to a server that does not
support the THREADS extension then the thread method will return
"undef".
The threads method will issue the THREAD command as defined in
http://www.ietf.org/internet-drafts/draft-ietf-imapext-thread-11.txt.
It returns an array of threads. Each element in the array is either a
message id or a reference to another array of (sub)threads.
If the "Uid" parameter is set to a true value then the message id's
returned in the thread structure will be message UID's. Otherwise they
will be message sequence numbers.
uidvalidity
Example:
my $validity = $imap->uidvalidity($folder)
or die "Could not uidvalidity: $@\n";
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.
unmark
Example:
$imap->unmark(@msgs) or die "Could not unmark: $@\n";
The unmark method accepts a list of one or more messages sequence
numbers, or a single reference to an array of one or more message
sequence numbers, as its argument(s). It then unsets the \Flagged flag
for those message(s). Of course, if the "Uid" parameter is set to a
true value then those message sequence numbers should really be unique
message id's.
Note that specifying "$imap->unmark(@msgs)" is just a shortcut for
specifying "$imap->unset_flag("Flagged",@msgs)".
Note also that the \Flagged flag is just one of many possible flags.
This is a little confusing, but you'll have to get used to the idea
that among the reserved flags specified in RFC3501 is one name
\Flagged. There is no specific meaning for this flag; it means
whatever the mailbox owner (or delegate) wants it to mean when it is
turned on.
unseen
Example:
my @unread = $imap->unseen or warn "Could not find unseen msgs: $@\n";
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.
Note that when specifying the flag in question, the preceding backslash
(\) is entirely optional.
unseen_count
Example:
foreach my $f ($imap->folders) {
print "The $f folder has ",
$imap->unseen_count($f)||0, " unseen messages.\n";
}
The unseen_count method accepts the name of a folder as an argument and
returns the number of unseen messages in that folder. If no folder
argument is provided then it returns the number of unseen messages in
the currently selected Folder.
unset_flag
Example:
$imap->unset_flag( "\Seen", @msgs )
or die "Could not unset_flag: $@\n";
The unset_flag method accepts the name of a flag as its first argument
and a list of one or more messages sequence numbers, or a single
reference to an array of one or more message sequence numbers, as its
next argument(s). It then unsets the flag specified for those
message(s). Of course, if the "Uid" parameter is set to a true value
then those message sequence numbers had better be unique message id's,
just as you'd expect.
Other IMAP Client Commands
Until release 2.99, when you called a method which did not exist, they
where automatically translated into an IMAP call with the same name via
an AUTOLOAD hack. This "feature" was removed for various reasons:
people made typos in the capitalization of method names, and the
program still seemed to work correctly. Besides, it blocked further
development of this module, because people did not contribute their
private extensions to the protocol implementation.
copy($msg, $folder)
Copy a message from the currently selected folder in the the folder
whose name is in $folder
subscribe($folder)
Subscribe to a folder
CAUTION: Once again, remember to quote your quotes (or use the "Quote"
method) 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"
operation, you can issue the following snippet:
my @raw = $imap->SEARCH("SUBJECT","Whatever...");
which is slightly more efficient than the equivalent:
$imap->search("SUBJECT","Whatever...");
my @raw = $imap->Results;
Of course you probably want the search results tucked nicely into a
list for you anyway, in which case you might as well use the "search"
method.
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:
Authmechanism
Example:
$imap->Authmechanism("CRAM-MD5");
# or
my $authmech = $imap->Authmechanism();
If specified, the Authmechanism causes the specified authentication
mechanism to be used whenever Mail::IMAPClient would otherwise invoke
login. If the value specified for the Authmechanism parameter is not a
valid authentication mechanism for your server then you will never ever
be able to log in again for the rest of your Perl script, probably. So
you might want to check, like this:
my $authmech = "CRAM-MD5";
$imap->has_capability($authmech) and $imap->Authmechanism($authmech);
Of course if you know your server supports your favorite authentication
mechanism then you know, so you can then include your Authmechanism
with your new call, as in:
my $imap = Mail::IMAPClient->new(
User => $user,
Passord => $passord,
Server => $server,
Authmechanism => $authmech,
%etc
);
If Authmechanism is supplied but Authcallback is not then you had
better be supporting one of the authentication mechanisms that
Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).
Authcallback
Example:
$imap->Authcallback( \&callback );
This specifies a default callback to the default authentication
mechanism (see "Authmechanism", above). Together, these two methods
replace automatic calls to login with automatic calls that look like
this (sort of):
$imap->authenticate($imap->Authmechanism,$imap->Authcallback);
If Authmechanism is supplied but Authcallback is not then you had
better be supporting one of the authentication mechanisms that
Mail::IMAPClient supports "out of the box" (such as CRAM-MD5).
Authuser
The Authuser parameter is used by the DIGEST-MD5 "Authmechanism".
Typically when you authenticate the username specified in the User
parameter is used. However, when using the DIGEST-MD5 Authmechanism
the Authuser can be used to specify a different username for the login.
This can be useful to mark messages as seen for the Authuser if you
don't know the password of the user as the seen state is often a per-
user state.
Buffer
Example:
$Buffer = $imap->Buffer();
# or:
$imap->Buffer($new_value);
The Buffer parameter sets the size of a block of I/O. It is ignored
unless "Fast_io", below, is set to a true value (the default), or
unless you are using the "migrate" method. It's value should be the
number of bytes to attempt to read in one I/O operation. The default
value is 4096.
When using the "migrate" method, you can often achieve dramatic
improvements in throughput by adjusting this number upward. However,
doing so also entails a memory cost, so if set too high you risk losing
all the benefits of the "migrate" method's chunking algorithm. Your
program can thus terminate with an "out of memory" error and you'll
have no one but yourself to blame.
Note that, as hinted above, the Buffer parameter affects the behavior
of the "migrate" method regardless of whether you have "Fast_io" turned
on. Believe me, you don't want to go around migrating tons of mail
without using buffered I/O!
Clear
Example:
$Clear = $imap->Clear();
# or:
$imap->Clear($integer);
The name of this parameter, for historical reasons, is somewhat
misleading. It should be named Wrap, because it specifies how many
transactions are stored in the wrapped history buffer. But it didn't
always work that way; the buffer used to actually get cleared. The
name though remains the same in the interests of backwards
compatibility.
Clear specifies that the object's history buffer should be wrapped
after every n transactions, where n is the value specified for the
Clear parameter. Calling the eponymous Clear method without an
argument will return the current value of the Clear parameter but will
not cause clear the history buffer to wrap.
Setting Clear to 0 turns off automatic history buffer wrapping, 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 (except of course for that inevitable last transaction).
The default Clear value is set to five (5) in order to conserve memory.
Compress
If set, Mail::IMAPClient attempts to enable use of the RFC4978 COMPRESS
DEFLATE extension. This requires that the server supports this
CAPABILITY. This attribute can be set to a true value to enable or an
ARRAYREF to control the arguments used in the call to
Compress::Zlib::deflateInit().
Mail::IMAPClient will automatically use Compress::Zlib to
deflate/inflate the data to/from the server. This attribute is used in
the "login" method.
See also "compress" and "capability".
Version note: attribute added in Mail::IMAPClient 3.30
Debug
Example:
$Debug = $imap->Debug();
# or:
$imap->Debug($true_or_false);
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. Use of this parameter is strongly recommended when
debugging scripts and required when reporting bugs.
Debug_fh
Example:
$Debug_fh = $imap->Debug_fh();
# or:
$imap->Debug_fh($fileHandle);
Specifies the file handle to which debugging information should be
printed. It can either a file handle object reference or a file handle
glob. The default is to print debugging info to STDERR.
For example, you can:
use Mail::IMAPClient;
use IO::File;
# set $user, $pass, and $server here
my $dh = IO::File->new(">debugging.output")
or die "Can't open debugging.output: $!\n";
my $imap = Mail::IMAPClient->new(
User=>$user, Password=>$pass, Server=>$server, Debug=>1, Debug_fh => $dh
);
which is the same as:
use Mail::IMAPClient;
use IO::File;
# set $user, $pass, and $server here
my $imap = Mail::IMAPClient->new(
User => $user,
Password => $pass,
Server => $server,
Debug => "yes, please",
Debug_fh => IO::File->new(">debugging.output")
|| die "Can't open debugging.output: $!\n"
);
You can also:
use Mail::IMAPClient;
# set $user, $pass, and $server here
open(DBG,">debugging.output")
or die "Can't open debugging.output: $!\n";
my $imap = Mail::IMAPClient->new(
User=>$user, Password=>$pass, Server=>$server, Debug=> 1, Debug_fh => *DBG
);
Specifying this parameter is not very useful unless "Debug" is set to a
true value.
Domain
The Domain parameter is used by the NTLM "Authmechanism". The domain
is an optional parameter for NTLM authentication.
EnableServerResponseInLiteral
Removed in 2.99_01 (now autodetect)
Fast_io
Example:
$Fast_io = $imap->Fast_io();
# or:
$imap->Fast_io($true_or_false);
The Fast_io parameter controls whether or not the Mail::IMAPClient
object will attempt to use non-blocking I/O on the IMAP socket. It is
turned on by default (unless the caller provides the socket to be
used).
See also "Buffer".
Folder
Example:
$Folder = $imap->Folder();
# or:
$imap->Folder($new_value);
The Folder parameter returns the name of the currently-selected folder
(in case you forgot). It can also be used to set the name of the
currently selected folder, which is completely unnecessary if you used
the "select" method (or "select"'s read-only equivalent, the "examine"
method) to select it.
Note that setting the Folder parameter does not automatically select a
new folder; you use the "select" or "examine" object methods for that.
Generally, the Folder parameter should only be queried (by using the
no-argument form of the Folder method). You will only need to set the
Folder parameter if you use some mysterious technique of your own for
selecting a folder, which you probably won't do.
Ignoresizeerrors
Certain (caching) servers, like Exchange 2007, often report the wrong
message size. Instead of chopping the message into a size that it fits
the specified size, the reported size will be simply ignored when this
parameter is set to 1.
Keepalive
Some firewalls and network gear like to timeout connections prematurely
if the connection sits idle. The Keepalive parameter, when set to a
true value, affects the behavior of "new" and "Socket" by enabling
SO_KEEPALIVE on the socket.
Version note: attribute added in Mail::IMAPClient 3.17
Maxcommandlength
The Maxcommandlength attribute is used by fetch() to limit length of
commands sent to a server. The default is 1000 chars, following the
recommendation of RFC2683 section 3.2.1.5.
Note: this attribute should also be used for several other methods but
this has not yet been implemented please feel free to file bugs for
methods where you run into problems with this.
This attribute should remove the need for utilities like imapsync to
create their own split() functions and instead allows Mail::IMAPClient
to DWIM.
In practice, this parameter has proven to be useful to overcome a limit
of 8000 octets for UW-IMAPD and 16384 octets for Courier/Cyrus IMAP
servers.
Version note: attribute added in Mail::IMAPClient 3.17
Maxtemperrors
Example:
$Maxtemperrors = $imap->Maxtemperrors();
# or:
$imap->Maxtemperrors($number);
The Maxtemperrors parameter specifies the number of times a read or
write operation is allowed to fail on a "Resource Temporarily
Available" (e.g. EAGAIN) error. The default setting is undef which
means there is no limit.
Setting this parameter to the string "unlimited" (instead of undef) to
ignore "Resource Temporarily Unavailable" errors is deprecated.
Note: This setting should be used with caution and may be removed in a
future release. Setting this can cause methods to return to the caller
before data is received (and then handled) properly thereby possibly
then leaving the module in a bad state. In the future, this behavior
may be changed in an attempt to avoid this situation.
Password
Example:
$Password = $imap->Password();
# or:
$imap->Password($new_value);
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.
Peek
Example:
$Peek = $imap->Peek();
# or:
$imap->Peek($true_or_false);
Setting Peek to a true value will prevent the "body_string",
"message_string" and "message_to_file" methods from automatically
setting the \Seen flag. Setting "Peek" to 0 (zero) will force
"body_string", "message_string", "message_to_file", and "parse_headers"
to always set the \Seen flag.
The default is to set the seen flag whenever you fetch the body of a
message but not when you just fetch the headers. Passing undef to the
eponymous Peek method will reset the Peek parameter to its pristine,
default state.
Port
Example:
$Port = $imap->Port();
# or:
$imap->Port($new_value);
Specifies the port on which the IMAP server is listening. A default
value of 993 (if "Ssl" is true) or 143 is set during a call to
"connect" if no value is provided by the caller. This argument can be
supplied with the "new" method call or separately by calling the "Port"
object method.
Prewritemethod
Prewritemethod parameter should contain a reference to a subroutine
that will do "special things" to data before it is sent to the IMAP
server (such as encryption or signing).
This method will be called immediately prior to sending an IMAP client
command to the server. Its first argument is a reference to the
Mail::IMAPClient object and the second argument is a string containing
the command that will be sent to the server. Your Prewritemethod
should return a string that has been signed or encrypted or whatever;
this returned string is what will actually be sent to the server.
Your Prewritemethod will probably need to know more than this to do
whatever it does. It is recommended that you tuck all other pertinent
information into a hash, and store a reference to this hash somewhere
where your method can get to it, possibly in the Mail::IMAPClient
object itself.
Note that this method should not actually send anything over the socket
connection to the server; it merely converts data prior to sending.
See also "Readmethod".
Ranges
Example:
$imap->Ranges(1);
# or:
my $search = $imap->search(@search_args);
if ( $imap->Ranges) { # $search is a MessageSet object
print "This is my condensed search result: $search\n";
print "This is every message in the search result: ",
join(",",@$search),"\n;
}
If set to a true value, then the "search" method will return a
Mail::IMAPClient::MessageSet object if called in a scalar context,
instead of the array reference that fetch normally returns when called
in a scalar context. If set to zero or if undefined, then search will
continue to return an array reference when called in scalar context.
This parameter has no affect on the search method when search is called
in a list context.
RawSocket
Example:
$socket = $imap->RawSocket;
# or:
$imap->RawSocket($socketh);
The RawSocket 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 (for instance an SSL handle, see
IO::Socket::SSL, but be sure to see the "Socket" method as well).
If you supply a socket handle yourself, either by doing something like:
$imap=Mail::IMAPClient->new(RawSocket => $sock, User => ... );
or by doing something like:
$imap = Mail::IMAPClient->new(User => $user,
Password => $pass, Server => $host);
# blah blah blah
$imap->RawSocket($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 until you're logged in. If you do any of this
then you should also set the "State" parameter yourself to reflect the
current state of the object (i.e. Connected, Authenticated, etc).
Note that no operation will be attempted on the socket when this method
is called. In particular, after the TCP connections towards the IMAP
server is established, the protocol mandates the server to send an
initial greeting message, and you will have to explicitly cope with
this message before doing any other operation, e.g. trying to call
"login". Caveat emptor.
For a more DWIM approach to setting the socket see "Socket".
Readmethod
Example:
$imap->Readmethod( # IMAP, HANDLE, BUFFER, LENGTH, OFFSET
sub {
my ( $self, $handle, $buffer, $count, $offset ) = @_;
my $rc = sysread( $handle, $$buffer, $count, $offset );
# do something useful here...
}
);
Readmethod should contain a reference to a subroutine that will replace
sysread. The subroutine will be passed the following arguments: first
the used Mail::IMAPClient object. Second, a reference to a socket.
Third, a reference to a scalar variable into which data is read
(BUFFER). The data placed here should be "finished data", so if you are
decrypting or removing signatures then be sure to do that before you
place data into this buffer. Fourth, the number of bytes requested to
be read; the LENGTH of the request. Lastly, the OFFSET into the BUFFER
where the data should be read. If not supplied it should default to
zero.
Note that this method completely replaces reads from the connection to
the server, so if you define one of these then your subroutine will
have to actually do the read. It is for things like this that we have
the "Socket" parameter and eponymous accessor method.
Your Readmethod will probably need to know more than this to do
whatever it does. It is recommended that you tuck all other pertinent
information into a hash, and store a reference to this hash somewhere
where your method can get to it, possibly in the Mail::IMAPClient
object itself.
See also "Prewritemethod".
Readmoremethod
Readmoremethod should contain a reference to a subroutine that will
replace/enhance the behavior of the internal _read_more() method. The
subroutine will be passed the following arguments: first the used
Mail::IMAPClient object. Second, a reference to a socket. Third, a
timeout value which is used as the timeout value for CORE::select() by
default. Depending upon changes/features introduced by Readmethod
changes may be required here.
Version note: attribute added in Mail::IMAPClient 3.30
Reconnectretry
If an IMAP connection sits idle too long, the connection may be closed
by the server or firewall, etc. The Reconnectretry parameter, when
given a positive integer value, will cause Mail::IMAPClient to retrying
IMAP commands up to X times when an EPIPE or ECONNRESET error occurs.
This is disabled (0) by default.
See also "Keepalive"
Version note: attribute added in Mail::IMAPClient 3.17
Server
Example:
$Server = $imap->Server();
# or:
$imap->Server($hostname);
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.
Showcredentials
Normally debugging output will mask the login credentials when the
plain text login mechanism is used. Setting Showcredentials to a true
value will suppress this, so that you can see the string being passed
back and forth during plain text login. Only set this to true when you
are debugging problems with the IMAP LOGIN command, and then turn it
off right away when you're finished working on that problem.
Example:
print "This is very risky!\n" if $imap->Showcredentials();
# or:
$imap->Showcredentials(0); # mask credentials again
Socket
PLEASE NOTE The semantics of this method has changed as of version
2.99_04 of this module. If you need the old semantics use "RawSocket".
Example:
$Socket = $imap->Socket();
# or:
$imap->Socket($socket_fh);
The Socket method can be used to obtain the socket handle of the
current connection. This may be necessary 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 (for instance an SSL handle, see
IO::Socket::SSL).
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
);
$imap->Socket($ssl);
then you are responsible for establishing the connection, i.e. make
sure that $ssl in the example is a valid and connected socket.
This method is primarily used to provide a drop-in replacement for
IO::Socket::INET, used by "connect" by default. In fact, this method
is called by "connect" itself after having established a suitable
IO::Socket::INET socket connection towards the target server; for this
reason, this method also carries the normal operations associated with
"connect", namely:
· read the initial greeting message from the server;
· call "login" if the conditions apply (see "connect" for details);
· leave the Mail::IMAPClient object in a suitable state.
For these reasons, the following example will work "out of the box":
use IO::Socket::SSL;
my $imap = Mail::IMAPClient->new
( User => 'your-username',
Password => 'your-password',
Socket => IO::Socket::SSL->new
( Proto => 'tcp',
PeerAddr => 'some.imap.server',
PeerPort => 993, # IMAP over SSL standard port
),
);
If you need more control over the socket, e.g. you have to implement a
fancier authentication method, see "RawSocket".
Starttls
If an IMAP connection must start TLS/SSL after connecting to a server
then set this attribute. If the value is set to an arrayref then they
will be used as arguments to IO::Socket::SSL::start_SSL. By default
this connection is set to blocking while establishing the connection
with a timeout of 30 seconds. The socket will be reset to the original
blocking/non-blocking value after a successful TLS negotiation has
occured.
Version note: attribute added in Mail::IMAPClient 3.22
Ssl
If an IMAP connection requires SSL you can set the Ssl attribute to '1'
and Mail::IMAPClient will automatically use IO::Socket::SSL instead of
IO::Socket::INET to connect to the server. This attribute is used in
the "connect" method.
See also "connect" for details on connection initiatiation and "Socket"
and "Rawsocket" if you need to take more control of connection
management.
Version note: attribute added in Mail::IMAPClient 3.18
Supportedflags
Especially when "migrate()" is used, the receiving peer may need to be
configured explicitly with the list of supported flags; that may be
different from the source IMAP server.
The names are to be specified as an ARRAY. Black-slashes and casing
will be ignored.
You may also specify a CODE reference, which will be called for each of
the flags separately. In this case, the flags are not (yet)
normalized. The returned lists of the CODE calls are shape the
resulting flag list.
Timeout
Example:
$Timeout = $imap->Timeout();
# or:
$imap->Timeout($seconds);
Specifies the timeout value in seconds for reads (default is 600).
Specifying a 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.
Setting Timeout to 0 (zero) disables the timeout feature.
Uid
Example:
$Uid = $imap->Uid();
# or:
$imap->Uid($true_or_false);
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 RFC3501, 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 folder names also have a unique identifier (UIDVALIDITY), which
is provided when the folder is "select"ed or "examine"d 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
parse_headers thread
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 @uids = $imap->search('SUBJECT',"Just a silly test"); #
$imap->Uid(0);
Example 2:
my @uids;
foreach $r ($imap->UID("SEARCH","SUBJECT","Just a silly test") {
chomp $r;
$r =~ s/\r$//;
$r =~ s/^\*\s+SEARCH\s+// or next;
push @uids, 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 an all-uppercase method name so as
not to inadvertently call the "Uid" accessor method. Then we parsed
out the message UIDs 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 (or just let it default to
being on) and then leave it on. (Remember that leaving it turned off
can lead to problems if changes to a folder's contents cause
resequencing.)
By default, the "Uid" parameter is turned on.
User
Example:
$User = $imap->User();
# or:
$imap->User($userid);
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.
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.
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:
Escaped_results
Example:
my @results = $imap->Escaped_results;
The Escaped_results method is almost identical to the History method.
Unlike the History method, however, server output transmitted literally
will be wrapped in double quotes, with all of the parentheses, double
quotes, backslashes, newlines, and carriage returns escaped. If called
in a scalar context, Escaped_results returns an array reference rather
than an array.
Escaped_results is useful if you are retrieving output and processing
it manually, and you are depending on the above special characters to
delimit the data. It is not useful when retrieving message contents;
use message_string or body_string for that.
History
Example:
my @history = $imap->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.
IsUnconnected
returns a true value if the object is currently in an "Unconnected"
state.
IsConnected
returns a true value if the object is currently in either a
"Connected", "Authenticated", or "Selected" state.
IsAuthenticated
returns a true value if the object is currently in either an
"Authenticated" or "Selected" state.
IsSelected
returns a true value if the object is currently in a "Selected" state.
LastError
Internally LastError is implemented just like a parameter (as described
in "Parameters", above). There is a LastError attribute and an
eponymous accessor method which returns the LastError text string
describing the last error condition encountered by the server.
Note that some errors are more serious than others, so LastError's
value is only meaningful if you encounter an error condition that you
don't like. For example, if you use the "exists" method to see if a
folder exists and the folder does not exist, then an error message will
be recorded in LastError even though this is not a particularly serious
error. On the other hand, if you didn't use "exists" and just tried to
"select" a non-existing folder, then "select" would return "undef"
after setting LastError to something like "NO SELECT failed: Can't open
mailbox "mailbox": no such mailbox". At this point it would be useful
to print out the contents of LastError as you die.
LastIMAPCommand
New in version 2.0.4, LastIMAPCommand returns the exact IMAP command
string to be sent to the server. Useful mainly in constructing error
messages when "LastError" just isn't enough.
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 many
transactions are in the report.
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.
State
The State method returns a numerical value that indicates the current
status of the IMAPClient object. If invoked with an argument, it will
set the object's state to that value. If invoked without an argument,
it behaves just like "Status", below.
Normally you will not have to invoke this function. An exception is if
you are bypassing the Mail::IMAPClient module's "connect" and/or
"login" modules to set up your own connection (say, for example, over a
secure socket), in which case you must manually do what the "connect"
and "login" methods would otherwise do for you.
Status
The Status method 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.)
Transaction
The Transaction method returns the tag value (or transaction number) of
the last IMAP client command.
Custom Authentication Mechanisms
If you just want to use plain text authentication or any of the
supported "Advanced Authentication Mechanisms" then there is no need to
read this section.
There are a number of methods and parameters that you can use to build
your own authentication mechanism. All of the methods and parameters
discussed in this section are described in more detail elsewhere in
this document. This section provides a starting point for building
your own authentication mechanism.
There are many authentication mechanisms out there, if your preferred
mechanism is not currently supported but you manage to get it working
please consider donating them to this module. Patches and suggestions
are always welcome.
Support for add-on authentication mechanisms in Mail::IMAPClient is
pretty straight forward. You create a callback to be used to provide
the response to the server's challenge. The "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 "Authmechanism" parameter or
as an argument to "authenticate".
You may also need to provide a subroutine to encrypt (or whatever) data
before it is sent to the server. The "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 "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 also 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 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, examples/imtestExample.pl, can be found in the "examples"
subdirectory of the source distribution.
The following list summarizes the methods and parameters that you may
find useful in implementing advanced authentication:
The authenticate method
The "authenticate" method uses the "Authmechanism" parameter to
determine how to authenticate with the server see the method
documentation for details.
Socket and RawSocket
The "Socket" and "RawSocket" methods provide access to the socket
connection. The socket is typically automatically created by the
"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
connect method completely. This is also useful if you want to use
IO::Socket::INET alternatives like IO::Socket::SSL and need full
control.
"RawSocket" simply gets/sets the socket without attempting any
interaction on it. In this case, you have to be sure to handle all
the preliminary operations and manually set the Mail::IMAPClient
object in sync with its actual status with respect to this socket
(see below for additional parameters regarding this, especially the
"State" parameter).
Unlike "RawSocket", "Socket" attempts to carry on preliminary
connection phases if the conditions apply. If both parameters are
present, this takes the precedence over "RawSocket". If "Starttls"
is set, then the "starttls" method will be called by "Socket".
PLEASE NOTE As of version 2.99_04 of this module, semantics for
"Socket" have changed to make it more "DWIM". "RawSocket" was
introduced as a replacement for the "Socket" parameter in older
version.
State, Server, User, Password, Proxy and Domain 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 Mail::IMAPClient object in sync with its actual status.
Of these, only the "State" parameter is always necessary. The
others need to be set only if you think your program will need them
later.
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 exists
primarily so that you can set it when you call "new" to instantiate
your object. The "new" method will call "connect", which will call
"login". If "login" sees that you have set an Authmechanism then
it will call authenticate, using your Authmechanism and
Authcallback parameters as arguments.
Authcallback
The "Authcallback", if set, holds a pointer to a subroutine
(CODEREF). The "login" method will use this as the callback
argument to the authenticate method if the Authmechanism and
Authcallback parameters are both set. If you set Authmechanism but
not Authcallback then the default callback for your mechanism will
be used. All supported authentication mechanisms have 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 "authenticate" method sends "<tag>
AUTHENTICATE <Authmechanism>\015\012" to the IMAP server, the
server replies with a challenge. The "authenticate" method then
invokes the code whose reference is stored in the Authcallback
parameter as follows:
$Authcallback->( $challenge, $imap )
where $Authcallback is the code reference stored in the
Authcallback parameter, $challenge is the challenge received from
the IMAP server, and $imap is a pointer to the Mail::IMAPClient
object. The return value from the Authcallback routine should be
the response to the challenge, and that return value will be sent
by the "authenticate" method to the server.
Prewritemethod/Readmethod
The Prewritemethod can hold a subroutine that will do whatever
encryption is necessary and then return the result to the caller so
it in turn can be sent to the server.
The Readmethod can hold a subroutine to be used to replace sysread
usually performed by Mail::IMAPClient.
See "Prewritemethod" and "Readmethod" for details.
REPORTING BUGS
Please send bug reports to "bug-Mail-IMAPClient@rt.cpan.org" or
http://rt.cpan.org/Public/Dist/Display.html?Name=Mail-IMAPClient
COPYRIGHT AND LICENSE
Copyright (C) 1999-2003 The Kernen Group, Inc.
Copyright (C) 2007-2009 Mark Overmeer
Copyright (C) 2010-2012 Phil Pearl (Lobbes)
All rights reserved.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself, either Perl version 5.8.0 or, at
your option, any later version of Perl 5 you may have available.
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.
perl v5.14.2 2012-08-08 Mail::IMAPClient(3)
