1Net::POP3(3pm)         Perl Programmers Reference Guide         Net::POP3(3pm)
2
3
4

NAME

6       Net::POP3 - Post Office Protocol 3 Client class (RFC1939)
7

SYNOPSIS

9           use Net::POP3;
10
11           # Constructors
12           $pop = Net::POP3->new('pop3host');
13           $pop = Net::POP3->new('pop3host', Timeout => 60);
14
15           if ($pop->login($username, $password) > 0) {
16             my $msgnums = $pop->list; # hashref of msgnum => size
17             foreach my $msgnum (keys %$msgnums) {
18               my $msg = $pop->get($msgnum);
19               print @$msg;
20               $pop->delete($msgnum);
21             }
22           }
23
24           $pop->quit;
25

DESCRIPTION

27       This module implements a client interface to the POP3 protocol,
28       enabling a perl5 application to talk to POP3 servers. This
29       documentation assumes that you are familiar with the POP3 protocol
30       described in RFC1939.
31
32       A new Net::POP3 object must be created with the new method. Once this
33       has been done, all POP3 commands are accessed via method calls on the
34       object.
35

CONSTRUCTOR

37       new ( [ HOST ] [, OPTIONS ] 0
38           This is the constructor for a new Net::POP3 object. "HOST" is the
39           name of the remote host to which an POP3 connection is required.
40
41           "HOST" is optional. If "HOST" is not given then it may instead be
42           passed as the "Host" option described below. If neither is given
43           then the "POP3_Hosts" specified in "Net::Config" will be used.
44
45           "OPTIONS" are passed in a hash like fashion, using key and value
46           pairs.  Possible options are:
47
48           Host - POP3 host to connect to. It may be a single scalar, as
49           defined for the "PeerAddr" option in IO::Socket::INET, or a
50           reference to an array with hosts to try in turn. The "host" method
51           will return the value which was used to connect to the host.
52
53           ResvPort - If given then the socket for the "Net::POP3" object will
54           be bound to the local port given using "bind" when the socket is
55           created.
56
57           Timeout - Maximum time, in seconds, to wait for a response from the
58           POP3 server (default: 120)
59
60           Debug - Enable debugging information
61

METHODS

63       Unless otherwise stated all methods return either a true or false
64       value, with true meaning that the operation was a success. When a
65       method states that it returns a value, failure will be returned as
66       undef or an empty list.
67
68       auth ( USERNAME, PASSWORD )
69           Attempt SASL authentication.
70
71       user ( USER )
72           Send the USER command.
73
74       pass ( PASS )
75           Send the PASS command. Returns the number of messages in the
76           mailbox.
77
78       login ( [ USER [, PASS ]] )
79           Send both the USER and PASS commands. If "PASS" is not given the
80           "Net::POP3" uses "Net::Netrc" to lookup the password using the host
81           and username. If the username is not specified then the current
82           user name will be used.
83
84           Returns the number of messages in the mailbox. However if there are
85           no messages on the server the string "0E0" will be returned. This
86           is will give a true value in a boolean context, but zero in a
87           numeric context.
88
89           If there was an error authenticating the user then undef will be
90           returned.
91
92       apop ( [ USER [, PASS ]] )
93           Authenticate with the server identifying as "USER" with password
94           "PASS".  Similar to "login", but the password is not sent in clear
95           text.
96
97           To use this method you must have the Digest::MD5 or the MD5 module
98           installed, otherwise this method will return undef.
99
100       banner ()
101           Return the sever's connection banner
102
103       capa ()
104           Return a reference to a hash of the capabilities of the server.
105           APOP is added as a pseudo capability.  Note that I've been unable
106           to find a list of the standard capability values, and some appear
107           to be multi-word and some are not.  We make an attempt at
108           intelligently parsing them, but it may not be correct.
109
110       capabilities ()
111           Just like capa, but only uses a cache from the last time we asked
112           the server, so as to avoid asking more than once.
113
114       top ( MSGNUM [, NUMLINES ] )
115           Get the header and the first "NUMLINES" of the body for the message
116           "MSGNUM". Returns a reference to an array which contains the lines
117           of text read from the server.
118
119       list ( [ MSGNUM ] )
120           If called with an argument the "list" returns the size of the
121           message in octets.
122
123           If called without arguments a reference to a hash is returned. The
124           keys will be the "MSGNUM"'s of all undeleted messages and the
125           values will be their size in octets.
126
127       get ( MSGNUM [, FH ] )
128           Get the message "MSGNUM" from the remote mailbox. If "FH" is not
129           given then get returns a reference to an array which contains the
130           lines of text read from the server. If "FH" is given then the lines
131           returned from the server are printed to the filehandle "FH".
132
133       getfh ( MSGNUM )
134           As per get(), but returns a tied filehandle.  Reading from this
135           filehandle returns the requested message.  The filehandle will
136           return EOF at the end of the message and should not be reused.
137
138       last ()
139           Returns the highest "MSGNUM" of all the messages accessed.
140
141       popstat ()
142           Returns a list of two elements. These are the number of undeleted
143           elements and the size of the mbox in octets.
144
145       ping ( USER )
146           Returns a list of two elements. These are the number of new
147           messages and the total number of messages for "USER".
148
149       uidl ( [ MSGNUM ] )
150           Returns a unique identifier for "MSGNUM" if given. If "MSGNUM" is
151           not given "uidl" returns a reference to a hash where the keys are
152           the message numbers and the values are the unique identifiers.
153
154       delete ( MSGNUM )
155           Mark message "MSGNUM" to be deleted from the remote mailbox. All
156           messages that are marked to be deleted will be removed from the
157           remote mailbox when the server connection closed.
158
159       reset ()
160           Reset the status of the remote POP3 server. This includes resetting
161           the status of all messages to not be deleted.
162
163       quit ()
164           Quit and close the connection to the remote POP3 server. Any
165           messages marked as deleted will be deleted from the remote mailbox.
166

NOTES

168       If a "Net::POP3" object goes out of scope before "quit" method is
169       called then the "reset" method will called before the connection is
170       closed. This means that any messages marked to be deleted will not be.
171

SEE ALSO

173       Net::Netrc, Net::Cmd
174

AUTHOR

176       Graham Barr <gbarr@pobox.com>
177
179       Copyright (c) 1995-2003 Graham Barr. All rights reserved.  This program
180       is free software; you can redistribute it and/or modify it under the
181       same terms as Perl itself.
182
183
184
185perl v5.12.4                      2011-06-01                    Net::POP3(3pm)
Impressum