Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Mail::Transport::POP3(User Contributed Perl DocumentatMail::Transport::POP3(3)

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  <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
	   interval => SECONDS
	   log => LEVEL
	   password => STRING
	   port	=> INTEGER
	   proxy => PATH
	   retry => NUMBER|undef
	   timeout => SECONDS
	   trace => LEVEL
	   use_ssl => BOOLEAN
	     To	set the	SSL parameters,	use IO::Socket::SSL subroutine
	     set_defaults.  Connections	will get restarted when	they are lost:
	     you have to keep the defaults in place during POP actions.

	   username => STRING
	   via => CLASS|NAME

   Attributes
       $obj->useSSL()
	   Returns "true" when SSL must	be used.

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

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

   Error handling
       Extends "Error handling"	in Mail::Transport::Receive.

       $obj->AUTOLOAD()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->addReport($object)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->defaultTrace( [$level]|[$loglevel,	$tracelevel]|[$level,
       $callback] )
       Mail::Transport::POP3->defaultTrace( [$level]|[$loglevel,
       $tracelevel]|[$level, $callback]	)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->errors()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->log( [$level, [$strings]] )
       Mail::Transport::POP3->log( [$level, [$strings]]	)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->logPriority($level)
       Mail::Transport::POP3->logPriority($level)
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->logSettings()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->notImplemented()
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->report( [$level] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->reportAll(	[$level] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->trace( [$level] )
	   Inherited, see "Error handling" in Mail::Reporter

       $obj->warnings()
	   Inherited, see "Error handling" in Mail::Reporter

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

       $obj->DESTROY()
	   Inherited, see "Cleanup" in Mail::Reporter

DIAGNOSTICS
       Error: Cannot connect to	$host:$port for	POP3: $!
	   Unsuccessful	in connecting to the remote POP3 server.

       Error: Cannot get the messages of pop3 via messages()
	   It is not possible to retrieve 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-POP3 distribution version 3.005,	built
       on May 03, 2019.	Website: http://perl.overmeer.net/CPAN/

LICENSE
       Copyrights 2001-2019 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://dev.perl.org/licenses/

perl v5.32.1			  2019-05-03	      Mail::Transport::POP3(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | DIAGNOSTICS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::Transport::POP3&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help