Frequently Asked Questions Regarding Mail::POP3Client
==============================================================

1. Does the module handle attachments?
2. How do I install it if my ISP won't?
3. Can I check to see if I have new mail?
4. How do I tell if the connection worked or not?
5. My ID and password are correct, why can't I connect?
6. Can't use an undefined value as a symbol reference [...] during global destruction.
6. Can't use an undefined value as a symbol reference [...] during global destruction.
7. How do I use an SSL connection?


Answers
==============================================================

1. Does the module handle attachments?

The module downloads messages in raw format.  It does not do anything
special with attachments.  To do that, use MIME::Parser or something
equivalent.  MIME::Parser has a method called parse_data that accepts
an array of lines.  Pass it the results of the Body method as follows:

    my $parser = new MIME::Parser;
    $parser->output_dir( $dir );
    my @lines = $pop->Body( $n );
    $parser->parse_data( @lines );

Or you can write straight to a temp file and have the parser process
that.

     my $io = new IO::File;
     if ($io->open( "> $dir/raw-message.$n")) {
       $pop3->HeadAndBodyToFile( $io, $n );
       $io->close;
       print "Parsing $dir/raw-message.$n...\n";
       $parser->parse( IO::File->new( "$dir/raw-message.$n") );
     }

See the perldoc for MIME::Parser for more details.


2. How do I install it if my ISP won't?

You have 2 choices.  You can go through the installation process using
a prefix option to the make command like this:

	% perl Makefile.PL prefix=/some/other/directory

then just make; make install as above.

Or you can create a directory called Mail somewhere and just put
POP3Client.pm in there.  You will then have to put this directory into
your include path (@INC) either on the command line or in your code
(i.e. use lib '/path/to/directory'; ).  You need to include the
directory above Mail and case does matter.

Choice 1 is better because you can track what modules you have
installed but if you don't have command line access you'll have to go
with choice 2.


3. Can I check to see if I have new mail?

Not directly.  You'd have to keep track of the messages read from the
last connection (using Uidl).  It's not something the protocol
supports.  Some mail servers may add a header when a message is
retrieved.  Try looking at the Status header.


4. How do I tell if the connection worked or not?

Check the Count() method.  A value of -1 means that the connection
failed.  You will have access to the other methods on the object to
see the Message, etc.  This will be changed sometime in the future so
that the constructor (or the Connect() method) will return undef or 0
on failure.


5. My ID and password are correct, why can't I connect?

Add AUTH_MODE => 'PASS' to the constructor.  Some servers state that
they support APOP authentication, but it may not work for all
accounts.


6. Can't use an undefined value as a symbol reference [...] during global destruction.

First, add 'use strict' and -w and fix all of the warnings in your
script.  If this error still occurs, please send me the type of server
you are using (telnet to port 110 on the server and send me the first
line it sends you).  Some POP3 servers drop the connection after a failed
authentication.  The servers I have tested against do not appear to do
this.

Another possibility that has been suggested is a situation with
redundant POP servers using DNS round robin.  If the first address
IO::Socket connects to is down, the module will fail to connect.


7. How do I use an SSL connection?  (Thanks to Jamie LeTual)

my $socket = IO::Socket::SSL->new( PeerAddr => 'pop.host.com',
				   PeerPort => 993,
				   Proto    => 'tcp') || die "Ack! No socket!";
my $pop = Mail::POP3Client->new();
$pop->User('jamie');
$pop->Pass('secret');
$pop->Socket($socket);
$pop->Connect();