Mail::Transport::POP3 • man page

Mail::Transport::POP3 (3)

Leading comments

Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Mail::Transport::POP3.3pm".)

NAME

Mail::Transport::POP3 - receive messages via POP3

INHERITANCE

Mail::Transport::POP3

is a Mail::Transport::Receive

is a Mail::Transport

is a Mail::Reporter

SYNOPSIS

my $receiver = Mail::Transport::POP3->new(...);

my $message = $receiver->receive($id);

DESCRIPTION

Receive messages via the POP3 protocol from one remote server, as specified in rfc1939. This object hides much of the complications in the protocol and recovers broken connections automatically. Although it is part of the MailBox distribution, this object can be used separately.

You probably should not use this module, but Mail::Box::POP3. This module is the interface to POP3, whereas Mail::Box::POP3 hides the protocol weirdness and works as any other mail folder.

Extends "DESCRIPTION" in Mail::Transport::Receive.

METHODS

Extends "METHODS" in Mail::Transport::Receive.

Constructors

Extends "Constructors" in Mail::Transport::Receive.

Mail::Transport::POP3->new(%options)

Create a new pop3 server connection. One object can only handle one connection: for a single user to one single server. If the server could not be reached, or when the login fails, this instantiating "new" will return "undef".

-Option --Defined in --Default

authenticate 'AUTO'

executable Mail::Transport undef

hostname Mail::Transport 'localhost'

interval Mail::Transport 30

log Mail::Reporter 'WARNINGS'

password Mail::Transport undef

port Mail::Transport 110

proxy Mail::Transport undef

retry Mail::Transport

timeout Mail::Transport 120

trace Mail::Reporter 'WARNINGS'

use_ssl

username Mail::Transport undef

via Mail::Transport 'sendmail'

authenticate => 'LOGIN'|'APOP'|'AUTO'

Authenthication method. The standard defines two methods, named LOGIN and APOP. The first sends the username and password in plain text to the server to get permission, the latter encrypts this data using MD5. When AUTO is used, first APOP is tried, and then LOGIN.

executable => FILENAME

hostname => HOSTNAME|ARRAY

interval => SECONDS

log => LEVEL

password => STRING

port => INTEGER

proxy => PATH

retry => NUMBER|undef

timeout => SECONDS

trace => LEVEL

use_ssl => BOOLEAN

username => STRING

via => CLASS|NAME

Receiving mail

Extends "Receiving mail" in Mail::Transport::Receive.

$obj->receive( [$unique_message_id] )

Inherited, see "Receiving mail" in Mail::Transport::Receive

Exchanging information

$obj->deleteFetched()

Mark all messages that have been fetched with message() for deletion. See fetched().

$obj->deleted(BOOLEAN, @ids)

Either mark the specified message(s) to be deleted on the remote server or unmark them for deletion (if the first parameter is false). Deletion of messages will take place only when the connection is specifically disconnected or the last reference to the object goes out of scope.

$obj->disconnect()

Break contact with the server, if that (still) exists. Returns true if successful. Please note that even if the disconnect was not successful, all knowledge of messages etc. will be removed from the object: the object basically has reverted to the state in which it was before anything was done with the mail box.

$obj->fetched()

Returns a reference to a list of ID's that have been fetched using message(). This can be used to update a database of messages that were fetched (but maybe not yet deleted) from the mailbox.

Please note that if the POP3 server did not support the UIDL command, this method will always return undef because it is not possibly to reliably identify messages between sessions (other than looking at the contents of the messages themselves).

Protocol internals

The follow methods handle protocol internals, and should not be used by a normal user of this class.

$obj->login()

Establish a new connection to the POP3 server, using username and password.

$obj->send($socket, $data)

Send $data to the indicated socket and return the first line read from that socket. Logs an error if either writing to or reading from socket failed.

This method does not attempt to reconnect or anything: if reading or writing the socket fails, something is very definitely wrong.

$obj->sendList($socket, $command)

Sends the indicated $command to the specified socket, and retrieves the response. It returns a reference to an array with all the lines that were reveived after the first "+OK" line and before the end-of-message delimiter (a single dot on a line). Returns "undef" whenever something has gone wrong.

$obj->socket()

Returns a connection to the POP3 server. If there was no connection yet, it will be created transparently. If the connection with the POP3 server was lost, it will be reconnected and the assures that internal state information (STAT and UIDL) is up-to-date in the object.

If the contact to the server was still present, or could be established, an IO::Socket::INET object is returned. Else, "undef" is returned and no further actions should be tried on the object.

$obj->status($socket)

Update the current status of folder on the remote POP3 server.

Server connection

Extends "Server connection" in Mail::Transport::Receive.

$obj->findBinary( $name, [@directories] )

Inherited, see "Server connection" in Mail::Transport

$obj->remoteHost()

Inherited, see "Server connection" in Mail::Transport

$obj->retry()

Inherited, see "Server connection" in Mail::Transport

$obj->url()

Represent this pop3 connection as URL.