1Mail::Transport::POP3(3U)ser Contributed Perl DocumentatiMoanil::Transport::POP3(3)
2
3
4
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 spec‐
20 ified in rfc1939. This object hides much of the complications in the
21 protocol and recovers broken connections automatically. Although it is
22 part of the MailBox distribution, this object can be used separately.
23
24 You probably should not use this module, but Mail::Box::POP3. This
25 module is the interface to POP3, whereas Mail::Box::POP3 hides the pro‐
26 tocol weirdness and works as any other mail folder.
27
29 Constructors
30
31 Mail::Transport::POP3->new(OPTIONS)
32
33 Create a new pop3 server connection. One object can only handle
34 one connection: for a single user to one single server. If the
35 server could not be reached, or when the login fails, this instan‐
36 tiating "new" will return "undef".
37
38 Option --Defined in --Default
39 authenticate 'AUTO'
40 executable Mail::Transport undef
41 hostname Mail::Transport 'localhost'
42 interval Mail::Transport 30
43 log Mail::Reporter 'WARNINGS'
44 password Mail::Transport undef
45 port Mail::Transport 110
46 proxy Mail::Transport undef
47 retry Mail::Transport <false>
48 timeout Mail::Transport 120
49 trace Mail::Reporter 'WARNINGS'
50 username Mail::Transport undef
51 via Mail::Transport 'sendmail'
52
53 . authenticate 'LOGIN'⎪'APOP'⎪'AUTO'
54
55 Authenthication method. The standard defines two methods,
56 named LOGIN and APOP. The first sends the username and pass‐
57 word in plain text to the server to get permission, the latter
58 encrypts this data using MD5. When AUTO is used, first APOP is
59 tried, and then LOGIN.
60
61 . executable FILENAME
62
63 . hostname HOSTNAME⎪ARRAY-OF-HOSTNAMES
64
65 . interval SECONDS
66
67 . log LEVEL
68
69 . password STRING
70
71 . port INTEGER
72
73 . proxy PATH
74
75 . retry NUMBER⎪undef
76
77 . timeout SECONDS
78
79 . trace LEVEL
80
81 . username STRING
82
83 . via CLASS⎪NAME
84
85 Receiving mail
86
87 $obj->receive([UNIQUE-MESSAGE-ID])
88
89 See "Receiving mail" in Mail::Transport::Receive
90
91 Exchanging information
92
93 $obj->deleteFetched
94
95 Mark all messages that have been fetched with message() for dele‐
96 tion. See fetched().
97
98 $obj->deleted(BOOLEAN, ID's)
99
100 Either mark the specified message(s) to be deleted on the remote
101 server or unmark them for deletion (if the first parameter is
102 false). Deletion of messages will take place only when the connec‐
103 tion is specifically disconnected or the last reference to the
104 object goes out of scope.
105
106 $obj->disconnect
107
108 Break contact with the server, if that (still) exists. Returns
109 true if successful. Please note that even if the disconnect was
110 not successful, all knowledge of messages etc. will be removed from
111 the object: the object basically has reverted to the state in which
112 it was before anything was done with the mail box.
113
114 $obj->fetched
115
116 Returns a reference to a list of ID's that have been fetched using
117 message(). This can be used to update a database of messages that
118 were fetched (but maybe not yet deleted) from the mailbox.
119
120 Please note that if the POP3 server did not support the UIDL com‐
121 mand, this method will always return undef because it is not possi‐
122 bly to reliably identify messages between sessions (other than
123 looking at the contents of the messages themselves).
124
125 See also deleteFetched().
126
127 $obj->folderSize
128
129 Returns the total number of octets used by the mailbox on the
130 remote server.
131
132 $obj->header(ID, [BODYLINES])
133
134 Returns a reference to an array which contains the header of the
135 message with the specified ID. "undef" is returned if something
136 has gone wrong.
137
138 The optional integer BODYLINES specifies the number of lines from
139 the body which should be added, by default none.
140
141 Example:
142
143 my $ref_lines = $pop3->header($uidl);
144 print @$ref_lines;
145
146 $obj->id2n(ID)
147
148 Translates the unique ID of a message into a sequence number which
149 represents the message as long a this connection to the POP3 server
150 exists. When the message has been deleted for some reason, "undef"
151 is returned.
152
153 $obj->ids
154
155 Returns a list (in list context) or a reference to a list (in
156 scalar context) of all ID's which are known by the server on this
157 moment.
158
159 $obj->message(ID)
160
161 Returns a reference to an array which contains the lines of the
162 message with the specified ID. Returns "undef" if something has
163 gone wrong.
164
165 Example:
166
167 my $ref_lines = $pop3->message($uidl);
168 print @$ref_lines;
169
170 $obj->messageSize(ID)
171
172 Returns the size of the message which is indicated by the ID, in
173 octets. If the message has been deleted on the remote server, this
174 will return "undef".
175
176 $obj->messages
177
178 Returns (in scalar context only) the number of messages that are
179 known to exist in the mailbox.
180
181 Protocol internals
182
183 The follow methods handle protocol internals, and should not be used by
184 a normal user of this class.
185
186 $obj->login
187
188 Establish a new connection to the POP3 server, using username and
189 password.
190
191 $obj->send(SOCKET, data)
192
193 Send data to the indicated socket and return the first line read
194 from that socket. Logs an error if either writing to or reading
195 from socket failed.
196
197 This method does not attempt to reconnect or anything: if reading
198 or writing the socket fails, something is very definitely wrong.
199
200 $obj->sendList(SOCKET, COMMAND)
201
202 Sends the indicated COMMAND to the specified socket, and retrieves
203 the response. It returns a reference to an array with all the
204 lines that were reveived after the first "+OK" line and before the
205 end-of-message delimiter (a single dot on a line). Returns "undef"
206 whenever something has gone wrong.
207
208 $obj->socket
209
210 Returns a connection to the POP3 server. If there was no connec‐
211 tion yet, it will be created transparently. If the connection with
212 the POP3 server was lost, it will be reconnected and the assures
213 that internal state information (STAT and UIDL) is up-to-date in
214 the object.
215
216 If the contact to the server was still present, or could be estab‐
217 lished, an IO::Socket::INET object is returned. Else, "undef" is
218 returned and no further actions should be tried on the object.
219
220 $obj->status(SOCKET)
221
222 Update the current status of folder on the remote POP3 server.
223
224 Server connection
225
226 $obj->findBinary(NAME [, DIRECTORIES])
227
228 See "Server connection" in Mail::Transport
229
230 $obj->remoteHost
231
232 See "Server connection" in Mail::Transport
233
234 $obj->retry
235
236 See "Server connection" in Mail::Transport
237
238 $obj->url
239
240 Represent this pop3 connection as URL.
241
242 Error handling
243
244 $obj->AUTOLOAD
245
246 See "Error handling" in Mail::Reporter
247
248 $obj->addReport(OBJECT)
249
250 See "Error handling" in Mail::Reporter
251
252 $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
253
254 Mail::Transport::POP3->defaultTrace([LEVEL]⎪[LOGLEVEL,
255 TRACELEVEL]⎪[LEVEL, CALLBACK])
256
257 See "Error handling" in Mail::Reporter
258
259 $obj->errors
260
261 See "Error handling" in Mail::Reporter
262
263 $obj->log([LEVEL [,STRINGS]])
264
265 Mail::Transport::POP3->log([LEVEL [,STRINGS]])
266
267 See "Error handling" in Mail::Reporter
268
269 $obj->logPriority(LEVEL)
270
271 Mail::Transport::POP3->logPriority(LEVEL)
272
273 See "Error handling" in Mail::Reporter
274
275 $obj->logSettings
276
277 See "Error handling" in Mail::Reporter
278
279 $obj->notImplemented
280
281 See "Error handling" in Mail::Reporter
282
283 $obj->report([LEVEL])
284
285 See "Error handling" in Mail::Reporter
286
287 $obj->reportAll([LEVEL])
288
289 See "Error handling" in Mail::Reporter
290
291 $obj->trace([LEVEL])
292
293 See "Error handling" in Mail::Reporter
294
295 $obj->warnings
296
297 See "Error handling" in Mail::Reporter
298
299 Cleanup
300
301 $obj->DESTROY
302
303 See "Cleanup" in Mail::Reporter
304
305 $obj->inGlobalDestruction
306
307 See "Cleanup" in Mail::Reporter
308
310 Error: Cannot connect to $host:$port for POP3: $!
311
312 Unsuccesful in connecting to the remote POP3 server.
313
314 Error: Cannot get the messages of pop3 via messages()
315
316 It is not possible to retreive all messages on a remote POP3 folder at
317 once: each shall be taken separately. The POP3 folder will hide this
318 for you.
319
320 Error: Cannot re-connect reliably to server which doesn't support UIDL.
321
322 The connection to the remote POP3 was lost, and cannot be re-estab‐
323 lished because the server's protocol implementation lacks the necessary
324 information.
325
326 Error: Cannot read POP3 from socket: $!
327
328 It is not possible to read the success status of the previously given
329 POP3 command. Connection lost?
330
331 Error: Cannot write POP3 to socket: $@
332
333 It is not possible to send a protocol command to the POP3 server. Con‐
334 nection lost?
335
336 Error: Could not authenticate using '$some' method.
337
338 The authenication method to get access to the POP3 server did not
339 result in a connection. Maybe you need a different authentication pro‐
340 tocol, or your username with password are invalid.
341
342 Error: Could not authenticate using any login method.
343
344 No authentication method was explicitly prescribed, so both AUTH and
345 APOP were tried. However, both failed. There are other authentication
346 methods, which are not defined by the main POP3 RFC rfc1939. These
347 protocols are not implemented yet. Please contribute your implementa‐
348 tion.
349
350 Error: POP3 Could not do a STAT
351
352 For some weird reason, the server does not respond to the STAT call.
353
354 Error: POP3 requires a username and password.
355
356 No username and/or no password specified for this POP3 folder, although
357 these are obligatory parts in the protocol.
358
359 Error: Package $package does not implement $method.
360
361 Fatal error: the specific package (or one of its superclasses) does not
362 implement this method where it should. This message means that some
363 other related classes do implement this method however the class at
364 hand does not. Probably you should investigate this and probably
365 inform the author of the package.
366
367 Error: Server at $host:$port does not seem to be talking POP3.
368
369 The remote server did not respond to an initial exchange of messages as
370 is expected by the POP3 protocol. The server has probably a different
371 service on the specified port.
372
374 This module is part of Mail-Box distribution version 2.070, built on
375 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
376
378 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
379 ChangeLog.
380
381 This program is free software; you can redistribute it and/or modify it
382 under the same terms as Perl itself. See
383 http://www.perl.com/perl/misc/Artistic.html
384
385
386
387perl v5.8.8 2007-03-25 Mail::Transport::POP3(3)