OVERLOADED

overload: ""
See "" in Mail::Box.
overload: @{}
See @{} in Mail::Box.
overload: cmp
See cmp in Mail::Box.

METHODS

See METHODS in Mail::Reporter

Constructors

$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 listSubFolders() to get the top-level folder names. Usually, the folder named INBOX will be present.

Option Defined in Default

access

Mail::Box

'r'

body_delayed_type

Mail::Box

Mail::Message::Body::Delayed

body_type

Mail::Box

Mail::Message::Body::Lines

cache_body

NO

cache_head

NO or DELAY

cache_labels

NO or DELAY

coerce_options

Mail::Box

[]

create

Mail::Box

<false>

extract

Mail::Box

10240

field_type

Mail::Box

undef

fix_headers

Mail::Box

<false>

folder

Mail::Box

/

folderdir

Mail::Box

<network location>

head_delayed_type

Mail::Box

Mail::Message::Head::Delayed

head_type

Mail::Box

Mail::Box::IMAP4::Head or Mail::Message::Head::Complete

join_connection

true

keep_dups

Mail::Box

<false>

lock_file

Mail::Box

undef

lock_timeout

Mail::Box

1 hour

lock_type

Mail::Box

'NONE'

lock_wait

Mail::Box

10 seconds

locker

Mail::Box

undef

log

Mail::Reporter

'WARNINGS'

manager

Mail::Box

undef

message_type

Mail::Box

Mail::Box::IMAP4::Message

multipart_type

Mail::Box

Mail::Message::Body::Multipart

password

Mail::Box::Net

undef

remove_when_empty

Mail::Box

<false>

save_on_exit

Mail::Box

<true>

server_name

Mail::Box::Net

undef

server_port

Mail::Box::Net

143

trace

Mail::Reporter

'WARNINGS'

transporter

Mail::Transport::IMAP4

trusted

Mail::Box

<false>

username

Mail::Box::Net

undef

access => MODE
body_delayed_type => CLASS
body_type => CLASS|CODE
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 wether 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 close(write). For folders which are opened read-write, the default is the safeset setting, which is NO.
coerce_options => ARRAY
create => BOOLEAN
extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
field_type => CLASS
fix_headers => BOOLEAN
folder => FOLDERNAME
folderdir => DIRECTORY
head_delayed_type => CLASS
head_type => CLASS
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.
keep_dups => BOOLEAN
lock_file => FILENAME
lock_timeout => SECONDS
lock_type => CLASS|STRING|ARRAY
lock_wait => SECONDS
locker => OBJECT
log => LEVEL
manager => MANAGER
message_type => CLASS
multipart_type => CLASS
password => STRING
remove_when_empty => BOOLEAN
save_on_exit => BOOLEAN
server_name => HOSTNAME
server_port => INTEGER
trace => LEVEL
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.
trusted => BOOLEAN
username => STRING
» 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);

The folder

$obj->addMessage( $message, %options )
See addMessage in Mail::Box.
$obj->addMessages( @messages )
See addMessages in Mail::Box.
$class->appendMessages( %options )
See appendMessages in Mail::Box.
$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()

Option Defined in Default

force

Mail::Box

<false>

save_deleted

Mail::Box

false

write

Mail::Box

MODIFIED

force => BOOLEAN
save_deleted => BOOLEAN
write => 'ALWAYS'|'NEVER'|'MODIFIED'
$obj->copyTo( $folder, %options )
See copyTo in Mail::Box.
$obj->delete( %options )
See delete in Mail::Box.
$obj->folderdir( [$directory] )
See folderdir in Mail::Box.
$obj->name
See name in Mail::Box.
$obj->organization
See organization in Mail::Box.
$obj->size
See size in Mail::Box.
$obj->type
See type in Mail::Box.
$obj->update( %options )
See update in Mail::Box.
$obj->url
See url in Mail::Box.

Folder flags

$obj->access
See access in Mail::Box.
$obj->isModified
See isModified in Mail::Box.
$obj->modified( [BOOLEAN] )
See modified in Mail::Box.
$obj->writable
See writable in Mail::Box.

The messages

$obj->current( [$number|$message|$message_id] )
See current in Mail::Box.
$obj->find( $message_id )
See find in Mail::Box.
$obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
See findFirstLabeled in Mail::Box.
$obj->message( $index, [$message] )
See message in Mail::Box.
$obj->messageId( $message_id, [$message] )
See messageId in Mail::Box.
$obj->messageIds
See messageIds in Mail::Box.
$obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label| !$label|$filter> )
See messages in Mail::Box.
$obj->nrMessages( %options )
See nrMessages in Mail::Box.
$obj->scanForMessages( $message, $message_ids, $timespan, $window )
See scanForMessages in Mail::Box.

Sub-folders

$obj->listSubFolders( %options )
$class->listSubFolders( %options )
See listSubFolders in Mail::Box.
$obj->nameOfSubFolder( $subname, [$parentname] )
$class->nameOfSubFolder( $subname, [$parentname] )
See nameOfSubFolder in Mail::Box.
$obj->openRelatedFolder( %options )
See openRelatedFolder in Mail::Box.
$obj->openSubFolder( $subname, %options )
See openSubFolder in Mail::Box.
$obj->topFolderWithMessages
$class->topFolderWithMessages
See topFolderWithMessages in Mail::Box.

Internals

$obj->body( [$body] )
$obj->coerce( $message, %options )
See coerce in Mail::Box.
$obj->create( $folder, %options )
$class->create( $folder, %options )
See create in Mail::Box::Net.
$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->determineBodyType( $message, $head )
See determineBodyType in Mail::Box.
$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.

$class->foundIn( [$foldername], %options )
See foundIn in Mail::Box.
$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->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
See lineSeparator in Mail::Box.
$obj->locker
See locker in Mail::Box.
$obj->read( %options )
See read in Mail::Box.
$obj->readMessages( %options )
See readMessages in Mail::Box.
$obj->storeMessage( $message )
See storeMessage in Mail::Box.
$obj->toBeThreaded( $messages )
See toBeThreaded in Mail::Box.
$obj->toBeUnthreaded( $messages )
See toBeUnthreaded in Mail::Box.
$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->updateMessages( %options )
See updateMessages in Mail::Box.
$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 Defined in Default

force

Mail::Box

<false>

save_deleted

<false>

force => BOOLEAN
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 Defined in Default

messages

Mail::Box

<required>

transporter

<required>

messages => ARRAY
transporter => OBJECT

Other methods

$obj->timespan2seconds( $time )
$class->timespan2seconds( $time )
See timespan2seconds in Mail::Box.

Error handling

$obj->AUTOLOAD
See AUTOLOAD in Mail::Reporter.
$obj->addReport( $object )
See addReport in Mail::Reporter.
$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
$class->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
See defaultTrace in Mail::Reporter.
$obj->errors
See errors in Mail::Reporter.
$obj->log( [$level, [$strings]] )
$class->log( [$level, [$strings]] )
See log in Mail::Reporter.
$obj->logPriority( $level )
$class->logPriority( $level )
See logPriority in Mail::Reporter.
$obj->logSettings
See logSettings in Mail::Reporter.
$obj->notImplemented
See notImplemented in Mail::Reporter.
$obj->report( [$level] )
See report in Mail::Reporter.
$obj->reportAll( [$level] )
See reportAll in Mail::Reporter.
$obj->trace( [$level] )
See trace in Mail::Reporter.
$obj->warnings
See warnings in Mail::Reporter.

Cleanup

$obj->DESTROY
See DESTROY in Mail::Box.