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

FreeBSD Manual Pages

  
 
  

home | help
Mail::POP3Client(3)   User Contributed Perl Documentation  Mail::POP3Client(3)

NAME
       Mail::POP3Client	- Perl 5 module	to talk	to a POP3 (RFC1939) server

SYNOPSIS
	 use Mail::POP3Client;
	 $pop =	new Mail::POP3Client( USER     => "me",
				      PASSWORD => "mypassword",
				      HOST     => "pop3.do.main" );
	 for( $i = 1; $i <= $pop->Count(); $i++	) {
	   foreach( $pop->Head(	$i ) ) {
	     /^(From|Subject):\s+/i && print $_, "\n";
	   }
	 }
	 $pop->Close();

	 # OR with SSL
	 $pop =	new Mail::POP3Client( USER     => "me",
				      PASSWORD => "mypassword",
				      HOST     => "pop3.do.main",
				      USESSL   => true,
				    );

	 # OR
	 $pop2 = new Mail::POP3Client( HOST  =>	"pop3.otherdo.main" );
	 $pop2->User( "somebody" );
	 $pop2->Pass( "doublesecret" );
	 $pop2->Connect() >= 0 || die $pop2->Message();
	 $pop2->Close();

	 # OR to use your own SSL socket...
	 my $socket = IO::Socket::SSL->new( PeerAddr =>	'pop.securedo.main',
					    PeerPort =>	993,
					    Proto    =>	'tcp') || die "No socket!";
	 my $pop = Mail::POP3Client->new();
	 $pop->User('somebody');
	 $pop->Pass('doublesecret');
	 $pop->Socket($socket);
	 $pop->Connect();

DESCRIPTION
       This module implements an Object-Oriented interface to a	POP3 server.
       It implements RFC1939 (http://www.faqs.org/rfcs/rfc1939.html)

EXAMPLES
       Here is a simple	example	to list	out the	From: and Subject: headers in
       your remote mailbox:

	 #!/usr/local/bin/perl

	 use Mail::POP3Client;

	 $pop =	new Mail::POP3Client( USER     => "me",
				      PASSWORD => "mypassword",
				      HOST     => "pop3.do.main" );
	 for ($i = 1; $i <= $pop->Count(); $i++) {
	   foreach ( $pop->Head( $i ) )	{
	     /^(From|Subject):\s+/i and	print $_, "\n";
	   }
	   print "\n";
	 }

CONSTRUCTORS
       Old style (deprecated):
	  new Mail::POP3Client(	USER, PASSWORD [, HOST,	PORT, DEBUG,
       AUTH_MODE] );

       New style (shown	with defaults):
	  new Mail::POP3Client(	USER	  => "",
				PASSWORD  => "",
				HOST	  => "pop3",
				PORT	  => 110,
				AUTH_MODE => 'BEST',
				DEBUG	  => 0,
				TIMEOUT	  => 60,
				LOCALADDR => 'xxx.xxx.xxx.xxx[:xx]',
				SOCKET => undef,
				USESSL => 0,
			      );

       o   USER	is the userID of the account on	the POP	server

       o   PASSWORD is the cleartext password for the userID

       o   HOST	is the POP server name or IP address (default =	'pop3')

       o   PORT	is the POP server port (default	= 110)

       o   DEBUG - any non-null, non-zero value	turns on debugging (default =
	   0)

       o   AUTH_MODE - pass 'APOP' to force APOP (MD5) authorization. (default
	   is 'BEST')

       o   TIMEOUT - set a timeout value for socket operations (default	= 60)

       o   LOCALADDR - allow selecting a local inet address to use

METHODS
       These commands are intended to make writing a POP3 client easier.  They
       do not necessarily map directly to POP3 commands	defined	in RFC1081 or
       RFC1939,	although all commands should be	supported.  Some commands
       return multiple lines as	an array in an array context.

       new( USER => 'user', PASSWORD =>	'password', HOST => 'host', PORT =>
       110, DEBUG => 0,	AUTH_MODE => 'BEST', TIMEOUT =>	60,, LOCALADDR =>
       'xxx.xxx.xxx.xxx[:xx]', SOCKET => undef,	USESSL => 0 ) )
	       Construct a new POP3 connection with this.  You should use the
	       hash-style constructor.	The old	positional constructor is
	       deprecated and will be removed in a future release.  It is
	       strongly	recommended that you convert your code to the new
	       version.

	       You should give it at least 2 arguments:	USER and PASSWORD.
	       The default HOST	is 'pop3' which	may or may not work for	you.
	       You can specify a different PORT	(be careful here).

	       new will	attempt	to Connect to and Login	to the POP3 server if
	       you supply a USER and PASSWORD.	If you do not supply them in
	       the constructor,	you will need to call Connect yourself.

	       The valid values	for AUTH_MODE are 'BEST', 'PASS', 'APOP' and
	       'CRAM-MD5'.  BEST says to try APOP if the server	appears	to
	       support it and it can be	used to	successfully log on, next try
	       similarly with CRAM-MD5,	and finally revert to PASS. APOP and
	       CRAM-MD5	imply that an MD5 checksum will	be used	instead	of
	       sending your password in	cleartext.  However, if	the server
	       does not	claim to support APOP or CRAM-MD5, the cleartext
	       method will be used. Be careful.	There are a few	servers	that
	       will send a timestamp in	the banner greeting, but APOP will not
	       work with them (for instance if the server does not know	your
	       password	in cleartext).	If you think your authentication
	       information is correct, run in DEBUG mode and look for errors
	       regarding authorization.	 If so,	then you may have to use
	       'PASS' for that server.	The same applies to CRAM-MD5, too.

	       If you enable debugging with DEBUG => 1,	socket traffic will be
	       echoed to STDERR.

	       Another warning,	it's impossible	to differentiate between a
	       timeout and a failure.

	       If you pass a true value	for USESSL, the	port will be changed
	       to 995 if it is not set or is 110.  Otherwise, it will use your
	       port.  If USESSL	is true, IO::Socket::SSL will be loaded.  If
	       it is not in your perl, the call	to connect will	fail.

	       new returns a valid Mail::POP3Client object in all cases.  To
	       test for	a connection failure, you will need to check the
	       number of messages: -1 indicates	a connection error.  This will
	       likely change sometime in the future to return undef on an
	       error, setting $! as a side effect.  This change	will not
	       happen in any 2.x version.

       Head( MESSAGE_NUMBER [, PREVIEW_LINES ] )
	       Get the headers of the specified	message, either	as an array or
	       as a string, depending on context.

	       You can also specify a number of	preview	lines which will be
	       returned	with the headers.  This	may not	be supported by	all
	       POP3 server implementations as it is marked as optional in the
	       RFC.  Submitted by Dennis Moroney <dennis@hub.iwl.net>.

       Body( MESSAGE_NUMBER )
	       Get the body of the specified message, either as	an array of
	       lines or	as a string, depending on context.

       BodyToFile( FILE_HANDLE,	MESSAGE_NUMBER )
	       Get the body of the specified message and write it to the given
	       file handle.  my	$fh = new IO::Handle();	$fh->fdopen( fileno(
	       STDOUT ), "w" );	$pop->BodyToFile( $fh, 1 );

	       Does no stripping of NL or CR.

       HeadAndBody( MESSAGE_NUMBER )
	       Get the head and	body of	the specified message, either as an
	       array of	lines or as a string, depending	on context.

	       Example
		   foreach ( $pop->HeadAndBody(	1 ) )
		      print $_,	"\n";

		   prints out the complete text	of message 1.

       HeadAndBodyToFile( FILE_HANDLE, MESSAGE_NUMBER )
	       Get the head and	body of	the specified message and write	it to
	       the given file handle.  my $fh =	new IO::Handle(); $fh->fdopen(
	       fileno( STDOUT ), "w" );	$pop->HeadAndBodyToFile( $fh, 1	);

	       Does no stripping of NL or CR.

       Retrieve( MESSAGE_NUMBER	)
	       Same as HeadAndBody.

       RetrieveToFile( FILE_HANDLE, MESSAGE_NUMBER )
	       Same as HeadAndBodyToFile.

       Delete( MESSAGE_NUMBER )
	       Mark the	specified message number as DELETED.  Becomes
	       effective upon QUIT (invoking the Close method).	 Can be	reset
	       with a Reset message.

       Connect Start the connection to the POP3	server.	 You can pass in the
	       host and	port.  Returns 1 if the	connection succeeds, or	0 if
	       it fails	(Message will contain a	reason).  The constructor
	       always returns a	blessed	reference to a Mail::POP3Client
	       obhect.	This may change	in a version 3.x release, but never in
	       a 2.x release.

       Close   Close the connection gracefully.	 POP3 says this	will perform
	       any pending deletes on the server.

       Alive   Return true or false on whether the connection is active.

       Socket  Return the file descriptor for the socket, or set if supplied.

       Size    Set/Return the size of the remote mailbox.  Set by POPStat.

       Count   Set/Return the number of	remote messages.  Set during Login.

       Message The last	status message received	from the server	or a message
	       describing any problem encountered.

       State   The internal state of the connection: DEAD, AUTHORIZATION,
	       TRANSACTION.

       POPStat Return the results of a POP3 STAT command.  Sets	the size of
	       the mailbox.

       List([message_number])
	       Returns the size	of the given message number when called	with
	       an argument using the following format:

		  <message_number> <size_in_bytes>

	       If message_number is omitted, List behaves the same as
	       ListArray, returning an indexed array of	the sizes of each
	       message in the same format.

	       You can parse the size in bytes using split:
		($msgnum, $size) = split('\s+',	$pop ->	List( n	));

       ListArray
	       Return a	list of	sizes of each message.	This returns an
	       indexed array, with each	message	number as an index (starting
	       from 1) and the value as	the next entry on the line.  Beware
	       that some servers send additional info for each message for the
	       list command.  That info	may be lost.

       Uidl( [MESSAGE_NUMBER] )
	       Return the unique ID for	the given message (or all of them).
	       Returns an indexed array	with an	entry for each valid message
	       number.	Indexing begins	at 1 to	coincide with the server's
	       indexing.

       Capa    Query server capabilities, as described in RFC 2449. Returns
	       the capabilities	in an array. Valid in all states.

       XTND    Optional	extended commands.  Transaction	state only.

       Last    Return the number of the	last message, retrieved	from the
	       server.

       Reset   Tell the	server to unmark any message marked for	deletion.

       User( [USER_NAME] )
	       Set/Return the current user name.

       Pass( [PASSWORD]	)
	       Set/Return the current user name.

       Login   Attempt to login	to the server connection.

       Host( [HOSTNAME]	)
	       Set/Return the current host.

       Port( [PORT_NUMBER] )
	       Set/Return the current port number.

IMAP COMPATIBILITY
       Basic Mail::IMAPClient method calls are also supported: close, connect,
       login, message_string, Password,	and unseen.  Also, empty stubs are
       provided	for Folder, folders, Peek, select, and Uid.

REQUIREMENTS
       This module does	not have mandatory requirements	for modules that are
       not part	of the standard	Perl distribution. However, APOP needs need
       Digest::MD5 and CRAM-MD5	needs Digest::HMAC_MD5 and MIME::Base64.

AUTHOR
       Sean Dowd <pop3client@dowds.net>

COPYRIGHT
       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

CREDITS
       Based loosely on	News::NNTPClient by Rodger Anderson
       <rodger@boi.hp.com>.

SEE ALSO
       perl(1)

       the Digest::MD5 manpage,	the Digest::HMAC_MD5 manpage, the MIME::Base64
       manpage

       RFC 1939: Post Office Protocol -	Version	3

       RFC 2195: IMAP/POP AUTHorize Extension for Simple Challenge/Response

       RFC 2449: POP3 Extension	Mechanism

perl v5.32.0			  2013-10-03		   Mail::POP3Client(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | CONSTRUCTORS | METHODS | IMAP COMPATIBILITY | REQUIREMENTS | AUTHOR | COPYRIGHT | CREDITS | SEE ALSO

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

home | help