NAME
Mail::Transport::POP3 - receive messages via POP3
CLASS 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 Mail::Box module, this object can be used separately.
METHODS
Initiation
- 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 returnundef
.OPTION DEFAULT authenticate 'AUTO' hostname 'localhost' interval 30 log 'WARNINGS' password undef port undef proxy undef retry <false> timeout 120 trace 'WARNINGS' username undef via '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.
- hostname => HOSTNAME|ARRAY-OF-HOSTNAMES
-
See Mail::Transport::new(hostname)
- interval => SECONDS
-
See Mail::Transport::new(interval)
- log => LEVEL
-
See Mail::Reporter::new(log)
- password => STRING
-
See Mail::Transport::new(password)
- port => INTEGER
-
See Mail::Transport::new(port)
- proxy => PATH
-
See Mail::Transport::new(proxy)
- retry => NUMBER|undef
-
See Mail::Transport::new(retry)
- timeout => SECONDS
-
See Mail::Transport::new(timeout)
- trace => LEVEL
-
See Mail::Reporter::new(trace)
- username => STRING
-
See Mail::Transport::new(username)
- via => CLASS|NAME
-
See Mail::Transport::new(via)
- url
-
Represent this pop3 connection as URL.
Server Connection
- findBinary NAME [, DIRECTORIES]
-
See Mail::Transport::findBinary()
- remoteHost
-
See Mail::Transport::remoteHost()
- retry
-
See Mail::Transport::retry()
Receiving Mail
Exchanging Information
- deleteFetched
-
Mark all messages that have been fetched with message() for deletion. See fetched().
- 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.
- 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.
- fetched
-
Returns a reference to a list of ID's that have been fetched using the message() method. 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().
- folderSize
-
Returns the total number of octets used by the mailbox on the remote server.
- 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.
Examples:
my $ref_lines = $pop3->header($uidl); print @$ref_lines;
- 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. - 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.
- 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.Examples:
my $ref_lines = $pop3->message($uidl); print @$ref_lines;
- 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
. - messages
-
Returns (in scalar context only) the number of messages that are known to exist in the mailbox.
Protocol [internals]
- 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.
- 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). Returnsundef
whenever something has gone wrong. - 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.
Logging and Tracing
- defaultTrace [LEVEL, [LEVEL]
-
See Mail::Reporter::defaultTrace()
- errors
-
See Mail::Reporter::errors()
- log [LEVEL [,STRINGS]]
-
See Mail::Reporter::log()
- report [LEVEL]
-
See Mail::Reporter::report()
- reportAll [LEVEL]
-
See Mail::Reporter::reportAll()
- trace [LEVEL]
-
See Mail::Reporter::trace()
- warnings
-
See Mail::Reporter::warnings()
Other Methods
- AUTOLOAD
-
See Mail::Reporter::AUTOLOAD()
- DESTROY
-
See Mail::Reporter::DESTROY()
- inGlobalDestruction
-
See Mail::Reporter::inGlobalDestruction()
- logPriority LEVEL
-
See Mail::Reporter::logPriority()
- logSettings
-
See Mail::Reporter::logSettings()
- notImplemented
-
See Mail::Reporter::notImplemented()
SEE ALSO
A good start to read is Mail::Box-Overview. More documentation and a mailinglist are available from the project's website at http://perl.overmeer.net/mailbox/.
AUTHOR
Written by Liz Mattijsen (liz@dijkmat.nl) and Mark Overmeer (mark@overmeer.net) with the help of many. See the ChangeLog for details.
VERSION
This code is beta, version 2.027.
Copyright (c) 2001-2002 by the authors. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.