1Mail::Transport::POP3(3U)ser Contributed Perl DocumentatiMoanil::Transport::POP3(3)
2
6 Mail::Transport::POP3 - receive messages via POP3
7
9 Mail::Transport::POP3
10 is a Mail::Transport::Receive
11 is a Mail::Transport
12 is a Mail::Reporter
13
15 my $receiver = Mail::Transport::POP3->new(...);
16 my $message = $receiver->receive($id);
17
19 Receive messages via the POP3 protocol from one remote server, as
20 specified in rfc1939. This object hides much of the complications in
21 the protocol and recovers broken connections automatically. Although
22 it is part of the MailBox distribution, this object can be used
23 separately.
24 You probably should not use this module, but Mail::Box::POP3. This
26 module is the interface to POP3, whereas Mail::Box::POP3 hides the
27 protocol weirdness and works as any other mail folder.
28
30 Constructors
31 Mail::Transport::POP3->new(OPTIONS)
32 Create a new pop3 server connection. One object can only handle
33 one connection: for a single user to one single server. If the
34 server could not be reached, or when the login fails, this
35 instantiating "new" will return "undef".
36 -Option --Defined in --Default
38 authenticate 'AUTO'
39 executable Mail::Transport undef
40 hostname Mail::Transport 'localhost'
41 interval Mail::Transport 30
42 log Mail::Reporter 'WARNINGS'
43 password Mail::Transport undef
44 port Mail::Transport 110
45 proxy Mail::Transport undef
46 retry Mail::Transport <false>
47 timeout Mail::Transport 120
48 trace Mail::Reporter 'WARNINGS'
49 use_ssl <false>
50 username Mail::Transport undef
51 via Mail::Transport 'sendmail'
52 authenticate => 'LOGIN'|'APOP'|'AUTO'
54 Authenthication method. The standard defines two methods, named
55 LOGIN and APOP. The first sends the username and password in
56 plain text to the server to get permission, the latter encrypts
57 this data using MD5. When AUTO is used, first APOP is tried, and
58 then LOGIN.
59 executable => FILENAME
61 hostname => HOSTNAME|ARRAY-OF-HOSTNAMES
62 interval => SECONDS
63 log => LEVEL
64 password => STRING
65 port => INTEGER
66 proxy => PATH
67 retry => NUMBER|undef
68 timeout => SECONDS
69 trace => LEVEL
70 use_ssl => BOOLEAN
71 username => STRING
72 via => CLASS|NAME
73 Receiving mail
75 $obj->receive([UNIQUE-MESSAGE-ID])
76 See "Receiving mail" in Mail::Transport::Receive
77 Exchanging information
79 $obj->deleteFetched
80 Mark all messages that have been fetched with message() for
81 deletion. See fetched().
82 $obj->deleted(BOOLEAN, ID's)
84 Either mark the specified message(s) to be deleted on the remote
85 server or unmark them for deletion (if the first parameter is
86 false). Deletion of messages will take place only when the
87 connection is specifically disconnected or the last reference to
88 the object goes out of scope.
89 $obj->disconnect
91 Break contact with the server, if that (still) exists. Returns
92 true if successful. Please note that even if the disconnect was
93 not successful, all knowledge of messages etc. will be removed from
94 the object: the object basically has reverted to the state in which
95 it was before anything was done with the mail box.
96 $obj->fetched
98 Returns a reference to a list of ID's that have been fetched using
99 message(). This can be used to update a database of messages that
100 were fetched (but maybe not yet deleted) from the mailbox.
101 Please note that if the POP3 server did not support the UIDL
103 command, this method will always return undef because it is not
104 possibly to reliably identify messages between sessions (other than
105 looking at the contents of the messages themselves).
106 See also deleteFetched().
108 $obj->folderSize
110 Returns the total number of octets used by the mailbox on the
111 remote server.
112 $obj->header(ID, [BODYLINES])
114 Returns a reference to an array which contains the header of the
115 message with the specified ID. "undef" is returned if something
116 has gone wrong.
117 The optional integer BODYLINES specifies the number of lines from
119 the body which should be added, by default none.
120 example:
122 my $ref_lines = $pop3->header($uidl);
124 print @$ref_lines;
125 $obj->id2n(ID)
127 Translates the unique ID of a message into a sequence number which
128 represents the message as long a this connection to the POP3 server
129 exists. When the message has been deleted for some reason, "undef"
130 is returned.
131 $obj->ids
133 Returns a list (in list context) or a reference to a list (in
134 scalar context) of all ID's which are known by the server on this
135 moment.
136 $obj->message(ID)
138 Returns a reference to an array which contains the lines of the
139 message with the specified ID. Returns "undef" if something has
140 gone wrong.
141 example:
143 my $ref_lines = $pop3->message($uidl);
145 print @$ref_lines;
146 $obj->messageSize(ID)
148 Returns the size of the message which is indicated by the ID, in
149 octets. If the message has been deleted on the remote server, this
150 will return "undef".
151 $obj->messages
153 Returns (in scalar context only) the number of messages that are
154 known to exist in the mailbox.
155 Protocol internals
157 The follow methods handle protocol internals, and should not be used by
158 a normal user of this class.
159 $obj->login
161 Establish a new connection to the POP3 server, using username and
162 password.
163 $obj->send(SOCKET, data)
165 Send data to the indicated socket and return the first line read
166 from that socket. Logs an error if either writing to or reading
167 from socket failed.
168 This method does not attempt to reconnect or anything: if reading
170 or writing the socket fails, something is very definitely wrong.
171 $obj->sendList(SOCKET, COMMAND)
173 Sends the indicated COMMAND to the specified socket, and retrieves
174 the response. It returns a reference to an array with all the
175 lines that were reveived after the first "+OK" line and before the
176 end-of-message delimiter (a single dot on a line). Returns "undef"
177 whenever something has gone wrong.
178 $obj->socket
180 Returns a connection to the POP3 server. If there was no
181 connection yet, it will be created transparently. If the
182 connection with the POP3 server was lost, it will be reconnected
183 and the assures that internal state information (STAT and UIDL) is
184 up-to-date in the object.
185 If the contact to the server was still present, or could be
187 established, an IO::Socket::INET object is returned. Else, "undef"
188 is returned and no further actions should be tried on the object.
189 $obj->status(SOCKET)
191 Update the current status of folder on the remote POP3 server.
192 Server connection
194 $obj->findBinary(NAME [, DIRECTORIES])
195 See "Server connection" in Mail::Transport
196 $obj->remoteHost
198 See "Server connection" in Mail::Transport
199 $obj->retry
201 See "Server connection" in Mail::Transport
202 $obj->url
204 Represent this pop3 connection as URL.
205 Error handling
207 $obj->AUTOLOAD
208 See "Error handling" in Mail::Reporter
209 $obj->addReport(OBJECT)
211 See "Error handling" in Mail::Reporter
212 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
214 Mail::Transport::POP3->defaultTrace([LEVEL]|[LOGLEVEL,
215 TRACELEVEL]|[LEVEL, CALLBACK])
216 See "Error handling" in Mail::Reporter
218 $obj->errors
220 See "Error handling" in Mail::Reporter
221 $obj->log([LEVEL [,STRINGS]])
223 Mail::Transport::POP3->log([LEVEL [,STRINGS]])
224 See "Error handling" in Mail::Reporter
226 $obj->logPriority(LEVEL)
228 Mail::Transport::POP3->logPriority(LEVEL)
229 See "Error handling" in Mail::Reporter
231 $obj->logSettings
233 See "Error handling" in Mail::Reporter
234 $obj->notImplemented
236 See "Error handling" in Mail::Reporter
237 $obj->report([LEVEL])
239 See "Error handling" in Mail::Reporter
240 $obj->reportAll([LEVEL])
242 See "Error handling" in Mail::Reporter
243 $obj->trace([LEVEL])
245 See "Error handling" in Mail::Reporter
246 $obj->warnings
248 See "Error handling" in Mail::Reporter
249 Cleanup
251 $obj->DESTROY
252 See "Cleanup" in Mail::Reporter
253 $obj->inGlobalDestruction
255 See "Cleanup" in Mail::Reporter
256
258 Error: Cannot connect to $host:$port for POP3: $!
259 Unsuccesful in connecting to the remote POP3 server.
260 Error: Cannot get the messages of pop3 via messages()
262 It is not possible to retreive all messages on a remote POP3 folder
263 at once: each shall be taken separately. The POP3 folder will hide
264 this for you.
265 Error: Cannot re-connect reliably to server which doesn't support UIDL.
267 The connection to the remote POP3 was lost, and cannot be re-
268 established because the server's protocol implementation lacks the
269 necessary information.
270 Error: Cannot read POP3 from socket: $!
272 It is not possible to read the success status of the previously
273 given POP3 command. Connection lost?
274 Error: Cannot write POP3 to socket: $@
276 It is not possible to send a protocol command to the POP3 server.
277 Connection lost?
278 Error: Could not authenticate using '$some' method.
280 The authenication method to get access to the POP3 server did not
281 result in a connection. Maybe you need a different authentication
282 protocol, or your username with password are invalid.
283 Error: Could not authenticate using any login method.
285 No authentication method was explicitly prescribed, so both AUTH
286 and APOP were tried. However, both failed. There are other
287 authentication methods, which are not defined by the main POP3 RFC
288 rfc1939. These protocols are not implemented yet. Please
289 contribute your implementation.
290 Error: POP3 Could not do a STAT
292 For some weird reason, the server does not respond to the STAT
293 call.
294 Error: POP3 requires a username and password.
296 No username and/or no password specified for this POP3 folder,
297 although these are obligatory parts in the protocol.
298 Error: Package $package does not implement $method.
300 Fatal error: the specific package (or one of its superclasses) does
301 not implement this method where it should. This message means that
302 some other related classes do implement this method however the
303 class at hand does not. Probably you should investigate this and
304 probably inform the author of the package.
305 Error: Server at $host:$port does not seem to be talking POP3.
307 The remote server did not respond to an initial exchange of
308 messages as is expected by the POP3 protocol. The server has
309 probably a different service on the specified port.
310
312 This module is part of Mail-Box distribution version 2.097, built on
313 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
314
316 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
317 ChangeLog.
318 This program is free software; you can redistribute it and/or modify it
320 under the same terms as Perl itself. See
321 http://www.perl.com/perl/misc/Artistic.html
322perl v5.12.3 2011-01-26 Mail::Transport::POP3(3)