METHODS

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

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

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

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

» 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->listSubFolders( %options )
$class->listSubFolders( %options )

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

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

authenticate

'AUTO'

pop_client

undef

ssl_options

<undef>

use_ssl

<false>

authenticate => 'LOGIN'|'APOP'|'AUTO'|'OUATH2'|'OAUTH2_SEP'
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.
[3.006] OAUTH* requires the authorization token to be passed as Password. Microsoft Office365 needs OAUTH2_SEP, where other oauth2 implementations use OAUTH2.
pop_client => OBJECT
You may want to specify your own pop-client object. The object which is passed must extend Mail::Transport::POP3.
ssl_options => HASH
use_ssl => BOOLEAN
» 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');
$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->update

NOT IMPLEMENTED YET

Internals

$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->popClient( %options )

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

Option Default

ssl_options

<from new(ssl_options)>

use_ssl

<from new(use_ssl)>

ssl_options => HASH
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->writeMessages( %options )
» 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.