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 )

For authentications, you have three choices: specify a foldername which resembles an URL, or specify a pop-client object, or separate options for user, password, pop-server and server-port.

Option Defined in Default

access

Mail::Box

'r'

authenticate

'AUTO'

body_delayed_type

Mail::Box

Mail::Message::Body::Delayed

body_type

Mail::Box

Mail::Message::Body::Lines

coerce_options

Mail::Box

[]

create

Mail::Box

<not applicable>

extract

Mail::Box

10240

field_type

Mail::Box

undef

fix_headers

Mail::Box

<false>

folder

Mail::Box

<not applicable>

folderdir

Mail::Box

<network location>

head_delayed_type

Mail::Box

Mail::Message::Head::Delayed

head_type

Mail::Box

Mail::Message::Head::Complete

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::POP3::Message

multipart_type

Mail::Box

Mail::Message::Body::Multipart

password

Mail::Box::Net

undef

pop_client

undef

remove_when_empty

Mail::Box

<false>

save_on_exit

Mail::Box

<true>

server_name

Mail::Box::Net

undef

server_port

Mail::Box::Net

110

trace

Mail::Reporter

'WARNINGS'

trusted

Mail::Box

<false>

username

Mail::Box::Net

undef

access => MODE
authenticate => 'LOGIN'|'APOP'|'AUTO'
POP3 can use two methods of authentication: the old LOGIN protocol, which transmits a username and password in plain text, and the newer APOP protocol which uses MD5 encryption. APOP is therefore much better, however not always supported by the server. With AUTO, first APOP is tried and if that fails LOGIN.
body_delayed_type => CLASS
body_type => CLASS|CODE
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
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
pop_client => OBJECT
You may want to specify your own pop-client object. The object which is passed must extend Mail::Transport::POP3.
remove_when_empty => BOOLEAN
save_on_exit => BOOLEAN
server_name => HOSTNAME
server_port => INTEGER
trace => LEVEL
trusted => BOOLEAN
username => STRING
» Example:
 my $url = 'pop3://user:password@pop.xs4all.nl'
 my $pop = Mail::Box::POP3->new($url);

 my $pop = $mgr->open(type => 'pop3',
    username => 'myname', password => 'mypassword',
    server_name => 'pop.xs4all.nl');

The folder

$obj->addMessage( $message )

It is impossible to write messages to the average POP3 server. There are extensions to the protocol which do permit it, however these are not implemented (yet, patches welcome).

undef is returned, and an error displayed. However, no complaint is given when the $message is undef itself.

Option Defined in Default

share

Mail::Box

<not used>

share => BOOLEAN
» Error: You cannot write a message to a pop server (yet)

Some extensions to the POP3 protocol do permit writing messages to the server, but the standard protocol only implements retreival. Feel invited to extend our implementation with writing.

$obj->addMessages( $messages )

As useless as addMessage(). The only acceptable call to this method is without any message.

$class->appendMessages( %options )
See appendMessages in Mail::Box.
$obj->close( %options )
See close in Mail::Box.
$obj->copyTo( $folder, %options )
See copyTo in Mail::Box.
$obj->delete( %options )

It is not possible to delete a POP3 folder remotely: the best we can do is remove all the messages in it... which is the action implemented here. A notice is logged about this.

Option Defined in Default

recursive

Mail::Box

<not used>

recursive => BOOLEAN
» Warning: POP3 folders cannot be deleted.

Each user has only one POP3 folder on a server. This folder is created and deleted by the server's administrator only.

$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

NOT IMPLEMENTED YET

$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 )

The standard POP3 protocol does not support sub-folders, so an empty list will be returned in any case.

Option Defined in Default

check

Mail::Box

<false>

folder

Mail::Box

<from calling object>

folderdir

Mail::Box

<from folder>

skip_empty

Mail::Box

<false>

check => BOOLEAN
folder => FOLDERNAME
folderdir => DIRECTORY
skip_empty => BOOL
$obj->nameOfSubFolder( $subname, [$parentname] )
$class->nameOfSubFolder( $subname, [$parentname] )
See nameOfSubFolder in Mail::Box.
$obj->openRelatedFolder( %options )
See openRelatedFolder in Mail::Box.
$obj->openSubFolder( %options )

It is not possible to open a sub-folder for a POP3 folder, because that is not supported by the official POP3 protocol. In any case, undef is returned to indicate a failure.

$obj->topFolderWithMessages
$class->topFolderWithMessages
See topFolderWithMessages in Mail::Box.

Internals

$obj->coerce( $message, %options )
See coerce in Mail::Box.
$obj->create( $folder, %options )
$class->create( $folder, %options )

It is not possible to create a new folder on a POP3 server. This method will always return false.

Option Defined in Default

folderdir

Mail::Box

undef

folderdir => DIRECTORY
$obj->determineBodyType( $message, $head )
See determineBodyType in Mail::Box.
$class->foundIn( [$foldername], %options )
See foundIn in Mail::Box.
$obj->getHead( $message )

Read the header for the specified message from the remote server.

$obj->getHeadAndBody( $message )

Read all data for the specified message from the remote server.

» Error: Cannot find head back for $uidl on POP3 server $name.

The server told to have this message, but when asked for its headers, no single line was returned. Did the message get destroyed?

» Error: Cannot read body for $uidl on POP3 server $name.

The message's headers are retrieved from the server, but the body seems to be lost. Did the message get destroyed between reading the header and reading the body?

» Warning: Message $uidl on POP3 server $name disappeared.

The server indicated the existence of this message before, however it has no information about the message anymore.

$obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
See lineSeparator in Mail::Box.
$obj->locker
See locker in Mail::Box.
$obj->popClient( %options )

Returns the pop client object. This does not establish the connection.

Option Default

use_ssl

<false>

use_ssl => BOOLEAN
» Error: Cannot create POP3 client for $name.

The connection to the POP3 server cannot be established. You may see more, related, error messages about the failure.

$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->updateMessages( %options )
See updateMessages in Mail::Box.
$obj->write( %options )
See write in Mail::Box.
$obj->writeMessages( %options )
Option Defined in Default

messages

Mail::Box

<required>

messages => ARRAY
» Error: Update of $nr messages ignored for POP3 folder $name.

The standard POP3 implementation does not support writing from client back to the server. Therefore, modifications may be lost.

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.