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.
METHODS¶
Constructors¶
- 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 <false>
timeout Mail::Transport 120
trace Mail::Reporter 'WARNINGS'
use_ssl <false>
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-OF-HOSTNAMES
- 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¶
- $obj->receive([UNIQUE-MESSAGE-ID])
- See "Receiving mail" in
Mail::Transport::Receive
- $obj->deleteFetched()
- Mark all messages that have been fetched with
message() for deletion. See fetched().
- $obj->deleted(BOOLEAN, ID's)
- 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).
See also deleteFetched().
- $obj->folderSize()
- Returns the total number of octets used by the mailbox on
the remote server.
- $obj->header(ID, [BODYLINES])
- Returns a reference to an array which contains the header
of the message with the specified ID. "undef" is returned if
something has gone wrong.
The optional integer BODYLINES specifies the number of lines from the body
which should be added, by default none.
example:
my $ref_lines = $pop3->header($uidl);
print @$ref_lines;
- $obj->id2n(ID)
- Translates the unique ID of a message into a sequence
number which represents the message as long a this connection to the POP3
server exists. When the message has been deleted for some reason,
"undef" is returned.
- $obj->ids()
- Returns a list (in list context) or a reference to a list
(in scalar context) of all ID's which are known by the server on this
moment.
- $obj->message(ID)
- Returns a reference to an array which contains the lines of
the message with the specified ID. Returns "undef" if something
has gone wrong.
example:
my $ref_lines = $pop3->message($uidl);
print @$ref_lines;
- $obj->messageSize(ID)
- Returns the size of the message which is indicated by the
ID, in octets. If the message has been deleted on the remote server, this
will return "undef".
- $obj->messages()
- Returns (in scalar context only) the number of messages
that are known to exist in the mailbox.
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¶
- $obj->findBinary(NAME [, DIRECTORIES])
- See "Server connection" in Mail::Transport
- $obj->remoteHost()
- See "Server connection" in Mail::Transport
- $obj->retry()
- See "Server connection" in Mail::Transport
- $obj->url()
- Represent this pop3 connection as URL.
Error handling¶
- $obj->AUTOLOAD()
- See "Error handling" in Mail::Reporter
- $obj->addReport(OBJECT)
- See "Error handling" in Mail::Reporter
- $obj->defaultTrace([LEVEL]|[LOGLEVEL,
TRACELEVEL]|[LEVEL, CALLBACK])
- Mail::Transport::POP3->defaultTrace([LEVEL]|[LOGLEVEL,
TRACELEVEL]|[LEVEL, CALLBACK])
- See "Error handling" in Mail::Reporter
- $obj->errors()
- See "Error handling" in Mail::Reporter
- $obj->log([LEVEL [,STRINGS]])
- Mail::Transport::POP3->log([LEVEL
[,STRINGS]])
- See "Error handling" in Mail::Reporter
- $obj->logPriority(LEVEL)
- Mail::Transport::POP3->logPriority(LEVEL)
- See "Error handling" in Mail::Reporter
- $obj->logSettings()
- See "Error handling" in Mail::Reporter
- $obj->notImplemented()
- See "Error handling" in Mail::Reporter
- $obj->report([LEVEL])
- See "Error handling" in Mail::Reporter
- $obj->reportAll([LEVEL])
- See "Error handling" in Mail::Reporter
- $obj->trace([LEVEL])
- See "Error handling" in Mail::Reporter
- $obj->warnings()
- See "Error handling" in Mail::Reporter
Cleanup¶
- $obj->DESTROY()
- See "Cleanup" in Mail::Reporter
- $obj->inGlobalDestruction()
- See "Cleanup" in Mail::Reporter
DIAGNOSTICS¶
- Error: Cannot connect to $host:$port for POP3: $!
- Unsuccesful in connecting to the remote POP3 server.
- Error: Cannot get the messages of pop3 via
messages()
- It is not possible to retreive all messages on a remote
POP3 folder at once: each shall be taken separately. The POP3 folder will
hide this for you.
- Error: Cannot re-connect reliably to server which doesn't
support UIDL.
- The connection to the remote POP3 was lost, and cannot be
re-established because the server's protocol implementation lacks the
necessary information.
- Error: Cannot read POP3 from socket: $!
- It is not possible to read the success status of the
previously given POP3 command. Connection lost?
- Error: Cannot write POP3 to socket: $@
- It is not possible to send a protocol command to the POP3
server. Connection lost?
- Error: Could not authenticate using '$some' method.
- The authenication method to get access to the POP3 server
did not result in a connection. Maybe you need a different authentication
protocol, or your username with password are invalid.
- Error: Could not authenticate using any login method.
- No authentication method was explicitly prescribed, so both
AUTH and APOP were tried. However, both failed. There are other
authentication methods, which are not defined by the main POP3 RFC
rfc1939. These protocols are not implemented yet. Please contribute your
implementation.
- Error: POP3 Could not do a STAT
- For some weird reason, the server does not respond to the
STAT call.
- Error: POP3 requires a username and password.
- No username and/or no password specified for this POP3
folder, although these are obligatory parts in the protocol.
- Error: Package $package does not implement $method.
- Fatal error: the specific package (or one of its
superclasses) does not implement this method where it should. This message
means that some other related classes do implement this method however the
class at hand does not. Probably you should investigate this and probably
inform the author of the package.
- Error: Server at $host:$port does not seem to be talking
POP3.
- The remote server did not respond to an initial exchange of
messages as is expected by the POP3 protocol. The server has probably a
different service on the specified port.
SEE ALSO¶
This module is part of Mail-Box distribution version 2.105, built on May 07,
2012. Website:
http://perl.overmeer.net/mailbox/
LICENSE¶
Copyrights 2001-2012 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself. See
http://www.perl.com/perl/misc/Artistic.html