METHODS

$obj->close( %options )

Close the folder. In the case of IMAP, more than one folder can use the same connection, therefore, closing a folder does not always close the connection to the server. Only when no folder is using the connection anymore, a logout will be invoked by Mail::Transport::IMAP4::DESTROY()

$class->new( %options )

The new can have many %options. Not only the ones listed here below, but also all the %options for Mail::Transport::IMAP4::new() can be passed.

The default depends on the value of new(cache_head).

Without folder name, no folder is selected. Only few methods are available now, for instance Mail::Box::IMAP4 subroutine listSubFolders to get the top-level folder names. Usually, the folder named INBOX will be present.

Option Default

cache_body

NO

cache_head

NO or DELAY

cache_labels

NO or DELAY

join_connection

true

transporter

Mail::Transport::IMAP4

cache_body => 'NO'|'YES'|'DELAY'
Body objects are immutable, but may still cached or not. In common case, the body of a message is requested via Mail::Message::body() or Mail::Message::decoded(). This returns a handle to a body object. You may decide whether that body object can be reused or not. NO means: retrieve the data each time again, YES will cache the body data, DELAY will send the whole message when the folder is closed.
        [local cache]  [write]
 NO         no           no
 YES        yes          no
 DELAY      yes          yes
cache_head => 'NO'|'PARTIAL'|'DELAY'
For a read-only folder, DELAY is the default, otherwise NO is chosen. The four configuration parameter have subtile consequences. To start with a table:
        [local cache]  [write]  [default head_type]
 NO         no           no     Mail::Box::IMAP4::Head
 PARTIAL    yes          no     Mail::Box::IMAP4::Head
 DELAY      yes          yes    Mail::Message::Head::Complete
The default head_type is Mail::Box::IMAP4::Head, the default cached_head_type is Mail::Message::Head::Complete.
Having a local cache means that a lookup for a field is first done in a local data-structure (which extends Mail::Message::Head::Partial), and only on the remote server if it was not found. This is dangerous, because your locally cached data can be out-of-sync with the server. However, it may give you a nice performance benefit.
DELAY will always collect the whole header for you. This is required when you want to look for Resent Groups (See Mail::Message::Head::ResentGroup) or other field order dependent header access. A Mail::Message::Head::Delayed will be created first.
cache_labels => 'NO'|'WRITE'|'DELAY'
When labels from a message are received, these values can be kept. However, this imposes dangers where the server's internal label storage may get out of sync with your data.
With NO, no caching will take place (but the performance will be worse). With WRITE, all label access will be cached, but written to the server as well. Both NO and WRITE will update the labels on the served, even when the folder was opened read-only. DELAY will not write the changed information to the server, but delay that till the moment that the folder is closed. It only works when the folder is opened read/write or write is enforced.
The default is DELAY for folders which where opened read-only. This means that you still can force an update with Mail::Box::IMAP4 subroutine close option write. For folders which are opened read-write, the default is the safeset setting, which is NO.
join_connection => BOOLEAN
Within this Mail::Box::IMAP4 class is registered which transporters are already in use, i.e. which connections to the IMAP server are already in established. When this option is set, multiple folder openings on the same server will try to reuse one connection.
transporter => OBJECT|CLASS
The name of the CLASS which will interface with the connection. When you implement your own extension to Mail::Transport::IMAP4, you can either specify a fully instantiated transporter OBJECT, or the name of your own CLASS. When an OBJECT is given, most other options will be ignored.
» Example:
 my $imap   = Mail::Box::IMAP4->new(username => 'myname',
    password => 'mypassword', server_name => 'imap.xs4all.nl');

 my $url    = 'imap4://user:password@imap.xs4all.nl';
 my $imap   = $mgr->open($url);

 my $client = Mail::IMAPClient->new(...);
 my $imap   = Mail::Box::IMAP4->new(imap_client => $client);

Internals

$obj->body( [$body] )
$obj->createTransporter( $class, %options )

Create a transporter object (an instance of Mail::Transport::IMAP4), where $class defines the exact object type. As %options, everything which is acceptable to a transporter initiation can be used (see Mail::Transport::IMAP4::new().

Option Default

join_connection

true

join_connection => BOOLEAN
See new(join_connection). When false, the connection will never be shared with other IMAP mail boxes.
$obj->fetch( <$messages|$selection>, $info )

Low-level data retreival about one or more messages via IMAP4 from the remote server. Some of this data may differ from the information which is stored in the message objects which are created by MailBox, so you should avoid the use of this method for your own purposes. The IMAP implementation provides some wrappers around this, providing the correct behavior.

An ARRAY of $messages may be specified or some message $selection, acceptable to Mail::Box::messages(). Examples of the latter are 'ALL', 'DELETED', or spam (messages labelled to contain spam).

The $info contains one or more attributes as defined by the IMAP protocol. You have to read the full specs of the related RFCs to see these.

$obj->getHead( $message )

Read the header for the specified message from the remote server. undef is returned in case the message disappeared.

» Warning: Message $uidl disappeared from $folder.

Trying to get the specific message from the server, but it appears to be gone.

$obj->getHeadAndBody( $message )

Read all data for the specified message from the remote server. Return head and body of the mesasge as list, or an empty list if the $message disappeared from the server.

» Warning: Cannot find head back for $uidl in $folder.

The header was read before, but now seems empty: the IMAP4 server does not produce the header lines anymore.

» Warning: Cannot read body for $uidl in $folder.

The header of the message was retrieved from the IMAP4 server, but the body is not read, for an unknown reason.

» Warning: Message $uidl disappeared from $folder.

Trying to get the specific message from the server, but it appears to be gone.

$obj->transporter( [$object] )

Returns the object which is the interface to the IMAP4 protocol handler. The IMAP4 handler has the current folder selected. When an $object is specified, it is set to be the transporter from that moment on. The $object must extend Mail::Transport::IMAP4.

» Error: Couldn't select IMAP4 folder $name
» Error: No IMAP4 transporter configured
$obj->write( %options )

The IMAP protocol usually writes the data immediately to the remote server, because that's what the protocol wants. However, some options to new() may delay that to boost performance. This method will, when the folder is being closed, write that info after all.

Option Default

save_deleted

undef

save_deleted => BOOLEAN
You may be able to save the messages which are flagged for deletion now, but they will be removed anyway when the folder is closed.
» Notice: Impossible to keep deleted messages in IMAP

Some folder type have a 'deleted' flag which can be stored in the folder to be performed later. The folder keeps that knowledge even when the folder is rewritten. Well, IMAP4 cannot play that trick.

$obj->writeMessages( %options )
Option Default

transporter

<required>

transporter => OBJECT

Error handling