- NAME
- SYNOPSIS
- DESCRIPTION

- new - constructor method
- connect - Connect to the POP account
- head_part - Access the email header
- all_head_parts - Access all email headers
- parse_message - Access an email
- message_save - Save an email
- stat - Do a STAT command
- list - Do a LIST command
- rset - Do an RSET command
- dele - Do a DELE command
- quit - Quit the connection
- uidl - Do a UIDL command
- count - Get the number of messages
- size - Get the size of all messages
- send - Send a raw command
- top - Retrieve the header
- retr - Retrieve an email

- REQUIREMENTS
- COPYRIGHT
- VERSION

# NAME

GT::Mail::POP3 - Receieve email through POP3 protocal

# SYNOPSIS

        use GT::Mail::POP3;

        my $pop = GT::Mail::POP3->new(
            host      => 'mail.gossamer-threads.com',
            port      => 110,
            user      => 'someusername',
            pass      => 'somepassword',
            auth_mode => 'PASS',
            timeout   => 30,
            debug     => 1
        );

        my $count = $pop->connect or die $GT::Mail::POP3::error;

        for my $num (1 .. $count) {
            my $top = $pop->parse_head($num);

            my @to = $top->split_field;

            if (grep /myfriend\@gossamer-threads\.com/, @to) {
                $pop->message_save($num, '/keep/email.txt');
                last;
            }
        }

# DESCRIPTION

GT::Mail::POP3 is a module to check an email account using the POP3 protocol. Many of the methods are integrated with the GT::Mail::Parse manpage.

## new - constructor method

This method is inherited from the GT::Base manpage. The argument to this method can be in the form of a hash or hash ref. As a minimum 'user', 'pass', and 'host' must be specified.

debug
  Sets the debugging level for this instance of GT::Mail::POP3.

host
  Sets the host to connect to for checking a POP account. This argument must be provided.

port
  Sets the port on the POP server to attempt to connect to. This defaults to 110, unless using SSL, for which the default is 995.

ssl
  Establishes the connection using SSL. Note that this requires Net::SSLeay of at least version 1.06.

user
  Sets the user name to login with when connecting to the POP server. This must be specified.

pass
  Sets the password to login with when connection to the POP server. This must be specified.

auth_mode
  Sets the authentication type for this connection. This can be one of two values. PASS (the default) or APOP. If set to APOP, GT::Mail::POP3 will use APOP to login to the remote server.

timeout
  Sets the connection timeout. This isn't entirely reliable as it uses alarm(), which isn't supported on all systems. That aside, this normally isn't needed if you want a timeout - it defaults to 30 on alarm()-supporting systems. The main purpose is to provide a value of 0 to disable the `alarm()` timeout.

## connect - Connect to the POP account

        $obj->connect or die $GT::Mail::POP3::error;

This method performs the connection to the POP server. Returns the count of messages on the server on success, and undefined on failure. Takes no arguments and called before you can perform any actions on the POP server.

## head_part - Access the email header

        # Get a parsed header part object for the first email in the list.
        my $top_part = $obj->head_part(1);

Instance method. The only argument to this method is the message number to get. Returns a the GT::Mail::Parts manpage object containing only the parsed header of the specified message.

## all_head_parts - Access all email headers

        # Get all the head parts from all messages
        my @headers = $obj->all_head_parts;

Instance method. Gets all the headers of all the email's on the remote server. Returns an array of the the GT::Mail::Parts manpage object. One object for each email. None of the email's bodies are retrieved, only the head.

## parse_message - Access an email

        # Parse an email and get the GT::Mail object
        my $mail = $obj->parse_message (1);

Instance method. Pass in the number of the email to retrieve. This method retrieves the specified email and returns the parsed GT::Mail object. If this method fails you should check $GT::Mail::error for the error message.

## message_save - Save an email

        open FH, '/path/to/email.txt' or die $!;

        # Save message 2 to file
        $obj->message_save (2, \*FH);
        close FH;

- or -

        $obj->message_save (2, '/path/to/email.txt') or die $GT::Mail::POP3::error;

Instance method. This method takes the message number as it's first argument, and either a file path or a file handle ref as it's second argument. If a file path is provided the file will be opened to truncate. The email is then retrieved from the server and written to the file.

## stat - Do a STAT command

        # Get the number of messages on the server
        my $count = $obj->stat;

Instance method. Does a STAT command on the remote server. It stores the total size and returns the count of messages on the server, if successful. Otherwise returns undef.

## list - Do a LIST command

        # At a list of messages on the server
        my @messages = $obj->list;

Instance method. Does a LIST command on the remote server. Returns an array of the lines in list context and a single scalar that contains all the lines in scalar context.

## rset - Do an RSET command

        # Tell the server to ignore any dele commands we have issued in this
        # session
        $obj->rset;

Instance method. Does an RSET command. This command resets the servers knowledge of what should be deleted when QUIT is called. Returns 1 on success.

## dele - Do a DELE command

        # Delete message 4
        $obj->dele (4);

Instance method. Does a DELE command. The only argument is the message number to delete. Returns 1 on success.

## quit - Quit the connection

        # Close our connection
        $obj->quit;

Instance method. Sends the QUIT command to the server. The should should disconnect soon after this. No more actions can be taken on this connection until connect is called again.

## uidl - Do a UIDL command

        # Get the uidl for message 1
        my $uidl = $obj->uidl (1);

        # Get a list of all the uidl's and print them
        $obj->uidl (sub { print @_ });

        # Get an array of all the uidl's
        my @uidl = $obj->uidl;

Instance method. Attempts to do a UIDL command on the remote server. Please be aware support for the UIDL command is not very wide spread. This method can take the message number as it's first argument. If the message number is given, the UIDL for that message is returned. If the first argument is a code reference, a UIDL command is done with no message specified and the code reference is called for each line returned from the remote server. If no second argument is given, a UIDL command is done, and the results are returned in a has of message number to UIDL.

## count - Get the number of messages

        # Get the count from the last STAT
        my $count = $obj->count;

This method returns the number of messages on the server from the last STAT command. A STAT is done on connect.

## size - Get the size of all messages

        # Get the total size of all messages on the server
        my $size = $obj->size;

This method returns the size of all messages in the server as returned by the last STAT command sent to the server.

## send - Send a raw command

        # Send a raw command to the server
        my $ret = $obj->send ("HELO");

This method sends the specified raw command to the POP server. The one line return from the server is returned. Do not call this method if you are expecting more than a one line response.

## top - Retrieve the header

        # Get the header of message 2 in an array.  New lines are stripped
        my @header = $obj->top (2);

        # Get the header as a string
        my $header = $obj->top (2);

Instance method to retrieve the top of an email on the POP server. The only argument should be the message number to retrieve. Returns a scalar containing the header in scalar context and an array, which is the scalar split on \015?\012, in list context.

## retr - Retrieve an email

        # Get message 3 from the remote server in an array.  New lines are stripped
        my @email = $obj->retr (3);

        # Get it as a string
        my $email = $obj->retr (3);

Instance method to retrieve an email from the POP server. The first argument to this method should be the message number to retrieve. The second argument is an optional code ref to call for each line of the message that is retrieved. If no code ref is specified, this method will put the email in a scalar and return the scalar in scalar context and return the scalar split on \015?\012 in list context.

# REQUIREMENTS

the GT::Socket::Client manpage the GT::Base manpage the GT::MD5 manpage (for APOP authentication)

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: POP3.pm,v 1.56 2004/03/19 00:36:16 brewt Exp $