1Mail::Box::POP3(3) User Contributed Perl Documentation Mail::Box::POP3(3)
2
3
4
6 Mail::Box::POP3 - handle POP3 folders as client
7
9 Mail::Box::POP3
10 is a Mail::Box::Net
11 is a Mail::Box
12 is a Mail::Reporter
13
14 Mail::Box::POP3 is extended by
15 Mail::Box::POP3s
16
18 use Mail::Box::POP3;
19 my $folder = Mail::Box::POP3->new(folder => $ENV{MAIL}, ...);
20
22 Maintain a folder which has its messages stored on a remote server.
23 The communication between the client application and the server is
24 implemented using the POP3 protocol. This class uses
25 Mail::Transport::POP3 to hide the transport of information, and
26 focusses solely on the correct handling of messages within a POP3
27 folder.
28
29 Extends "DESCRIPTION" in Mail::Box::Net.
30
32 Extends "OVERLOADED" in Mail::Box::Net.
33
34 overload: ""
35 Inherited, see "OVERLOADED" in Mail::Box
36
37 overload: @{}
38 Inherited, see "OVERLOADED" in Mail::Box
39
40 overload: cmp
41 Inherited, see "OVERLOADED" in Mail::Box
42
44 Extends "METHODS" in Mail::Box::Net.
45
46 Constructors
47 Extends "Constructors" in Mail::Box::Net.
48
49 Mail::Box::POP3->new(%options)
50 For authentications, you have three choices: specify a foldername
51 which resembles an URL, or specify a pop-client object, or separate
52 options for user, password, pop-server and server-port.
53
54 -Option --Defined in --Default
55 access Mail::Box 'r'
56 authenticate 'AUTO'
57 body_delayed_type Mail::Box Mail::Message::Body::Delayed
58 body_type Mail::Box Mail::Message::Body::Lines
59 coerce_options Mail::Box []
60 create Mail::Box <not applicable>
61 extract Mail::Box 10240
62 field_type Mail::Box undef
63 fix_headers Mail::Box <false>
64 folder Mail::Box <not applicable>
65 folderdir Mail::Box <network location>
66 head_delayed_type Mail::Box Mail::Message::Head::Delayed
67 head_type Mail::Box Mail::Message::Head::Complete
68 keep_dups Mail::Box <false>
69 lock_file Mail::Box undef
70 lock_timeout Mail::Box 1 hour
71 lock_type Mail::Box 'NONE'
72 lock_wait Mail::Box 10 seconds
73 locker Mail::Box undef
74 log Mail::Reporter 'WARNINGS'
75 manager Mail::Box undef
76 message_type Mail::Box Mail::Box::POP3::Message
77 multipart_type Mail::Box Mail::Message::Body::Multipart
78 password Mail::Box::Net undef
79 pop_client undef
80 remove_when_empty Mail::Box <false>
81 save_on_exit Mail::Box <true>
82 server_name Mail::Box::Net undef
83 server_port Mail::Box::Net 110
84 trace Mail::Reporter 'WARNINGS'
85 trusted Mail::Box <false>
86 username Mail::Box::Net undef
87
88 access => MODE
89 authenticate => 'LOGIN'|'APOP'|'AUTO'
90 POP3 can use two methods of authentication: the old LOGIN
91 protocol, which transmits a username and password in plain text,
92 and the newer APOP protocol which uses MD5 encryption. APOP is
93 therefore much better, however not always supported by the
94 server. With AUTO, first APOP is tried and if that fails LOGIN.
95
96 body_delayed_type => CLASS
97 body_type => CLASS|CODE
98 coerce_options => ARRAY
99 create => BOOLEAN
100 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
101 field_type => CLASS
102 fix_headers => BOOLEAN
103 folder => FOLDERNAME
104 folderdir => DIRECTORY
105 head_delayed_type => CLASS
106 head_type => CLASS
107 keep_dups => BOOLEAN
108 lock_file => FILENAME
109 lock_timeout => SECONDS
110 lock_type => CLASS|STRING|ARRAY
111 lock_wait => SECONDS
112 locker => OBJECT
113 log => LEVEL
114 manager => MANAGER
115 message_type => CLASS
116 multipart_type => CLASS
117 password => STRING
118 pop_client => OBJECT
119 You may want to specify your own pop-client object. The object
120 which is passed must extend Mail::Transport::POP3.
121
122 remove_when_empty => BOOLEAN
123 save_on_exit => BOOLEAN
124 server_name => HOSTNAME
125 server_port => INTEGER
126 trace => LEVEL
127 trusted => BOOLEAN
128 username => STRING
129
130 example:
131
132 my $url = 'pop3://user:password@pop.xs4all.nl'
133 my $pop = Mail::Box::POP3->new($url);
134
135 my $pop = $mgr->open(type => 'pop3',
136 username => 'myname', password => 'mypassword',
137 server_name => 'pop.xs4all.nl');
138
139 The folder
140 Extends "The folder" in Mail::Box::Net.
141
142 $obj->addMessage($message)
143 It is impossible to write messages to the average POP3 server.
144 There are extensions to the protocol which do permit it, however
145 these are not implemented (yet, patches welcome).
146
147 "undef" is returned, and an error displayed. However, no complaint
148 is given when the $message is "undef" itself.
149
150 -Option--Defined in--Default
151 share Mail::Box <not used>
152
153 share => BOOLEAN
154 $obj->addMessages($messages)
155 As useless as addMessage(). The only acceptable call to this
156 method is without any message.
157
158 Mail::Box::POP3->appendMessages(%options)
159 Inherited, see "The folder" in Mail::Box
160
161 $obj->close(%options)
162 Inherited, see "The folder" in Mail::Box
163
164 $obj->copyTo($folder, %options)
165 Inherited, see "The folder" in Mail::Box
166
167 $obj->delete(%options)
168 It is not possible to delete a POP3 folder remotely: the best we
169 can do is remove all the messages in it... which is the action
170 implemented here. A notice is logged about this.
171
172 -Option --Defined in--Default
173 recursive Mail::Box <not used>
174
175 recursive => BOOLEAN
176 $obj->folderdir( [$directory] )
177 Inherited, see "The folder" in Mail::Box
178
179 $obj->name()
180 Inherited, see "The folder" in Mail::Box
181
182 $obj->organization()
183 Inherited, see "The folder" in Mail::Box
184
185 $obj->size()
186 Inherited, see "The folder" in Mail::Box
187
188 $obj->type()
189 Inherited, see "The folder" in Mail::Box
190
191 $obj->update()
192 NOT IMPLEMENTED YET
193
194 $obj->url()
195 Inherited, see "The folder" in Mail::Box
196
197 Folder flags
198 Extends "Folder flags" in Mail::Box::Net.
199
200 $obj->access()
201 Inherited, see "Folder flags" in Mail::Box
202
203 $obj->isModified()
204 Inherited, see "Folder flags" in Mail::Box
205
206 $obj->modified( [BOOLEAN] )
207 Inherited, see "Folder flags" in Mail::Box
208
209 $obj->writable()
210 Inherited, see "Folder flags" in Mail::Box
211
212 The messages
213 Extends "The messages" in Mail::Box::Net.
214
215 $obj->current( [$number|$message|$message_id] )
216 Inherited, see "The messages" in Mail::Box
217
218 $obj->find($message_id)
219 Inherited, see "The messages" in Mail::Box
220
221 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
222 Inherited, see "The messages" in Mail::Box
223
224 $obj->message( $index, [$message] )
225 Inherited, see "The messages" in Mail::Box
226
227 $obj->messageId( $message_id, [$message] )
228 Inherited, see "The messages" in Mail::Box
229
230 $obj->messageIds()
231 Inherited, see "The messages" in Mail::Box
232
233 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
234 !$label|$filter> )
235 Inherited, see "The messages" in Mail::Box
236
237 $obj->nrMessages(%options)
238 Inherited, see "The messages" in Mail::Box
239
240 $obj->scanForMessages($message, $message_ids, $timespan, $window)
241 Inherited, see "The messages" in Mail::Box
242
243 Sub-folders
244 Extends "Sub-folders" in Mail::Box::Net.
245
246 $obj->listSubFolders(%options)
247 Mail::Box::POP3->listSubFolders(%options)
248 The standard POP3 protocol does not support sub-folders, so an
249 empty list will be returned in any case.
250
251 -Option --Defined in --Default
252 check Mail::Box <false>
253 folder Mail::Box <from calling object>
254 folderdir Mail::Box <from folder>
255 skip_empty Mail::Box <false>
256
257 check => BOOLEAN
258 folder => FOLDERNAME
259 folderdir => DIRECTORY
260 skip_empty => BOOL
261 $obj->nameOfSubFolder( $subname, [$parentname] )
262 Mail::Box::POP3->nameOfSubFolder( $subname, [$parentname] )
263 Inherited, see "Sub-folders" in Mail::Box
264
265 $obj->openRelatedFolder(%options)
266 Inherited, see "Sub-folders" in Mail::Box
267
268 $obj->openSubFolder(%options)
269 It is not possible to open a sub-folder for a POP3 folder, because
270 that is not supported by the official POP3 protocol. In any case,
271 "undef" is returned to indicate a failure.
272
273 $obj->topFolderWithMessages()
274 Mail::Box::POP3->topFolderWithMessages()
275 Inherited, see "Sub-folders" in Mail::Box
276
277 Internals
278 Extends "Internals" in Mail::Box::Net.
279
280 $obj->coerce($message, %options)
281 Inherited, see "Internals" in Mail::Box
282
283 $obj->create($folder, %options)
284 Mail::Box::POP3->create($folder, %options)
285 It is not possible to create a new folder on a POP3 server. This
286 method will always return "false".
287
288 -Option --Defined in--Default
289 folderdir Mail::Box undef
290
291 folderdir => DIRECTORY
292 $obj->determineBodyType($message, $head)
293 Inherited, see "Internals" in Mail::Box
294
295 Mail::Box::POP3->foundIn( [$foldername], %options )
296 Inherited, see "Internals" in Mail::Box
297
298 $obj->getHead($message)
299 Read the header for the specified message from the remote server.
300
301 $obj->getHeadAndBody($message)
302 Read all data for the specified message from the remote server.
303
304 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
305 Inherited, see "Internals" in Mail::Box
306
307 $obj->locker()
308 Inherited, see "Internals" in Mail::Box
309
310 $obj->popClient(%options)
311 Returns the pop client object. This does not establish the
312 connection.
313
314 -Option --Default
315 use_ssl <false>
316
317 use_ssl => BOOLEAN
318 $obj->read(%options)
319 Inherited, see "Internals" in Mail::Box
320
321 $obj->readMessages(%options)
322 Inherited, see "Internals" in Mail::Box
323
324 $obj->storeMessage($message)
325 Inherited, see "Internals" in Mail::Box
326
327 $obj->toBeThreaded($messages)
328 Inherited, see "Internals" in Mail::Box
329
330 $obj->toBeUnthreaded($messages)
331 Inherited, see "Internals" in Mail::Box
332
333 $obj->updateMessages(%options)
334 Inherited, see "Internals" in Mail::Box
335
336 $obj->write(%options)
337 Inherited, see "Internals" in Mail::Box
338
339 $obj->writeMessages(%options)
340 -Option --Defined in--Default
341 messages Mail::Box <required>
342
343 messages => ARRAY
344
345 Other methods
346 Extends "Other methods" in Mail::Box::Net.
347
348 $obj->timespan2seconds($time)
349 Mail::Box::POP3->timespan2seconds($time)
350 Inherited, see "Other methods" in Mail::Box
351
352 Error handling
353 Extends "Error handling" in Mail::Box::Net.
354
355 $obj->AUTOLOAD()
356 Inherited, see "Error handling" in Mail::Reporter
357
358 $obj->addReport($object)
359 Inherited, see "Error handling" in Mail::Reporter
360
361 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
362 $callback] )
363 Mail::Box::POP3->defaultTrace( [$level]|[$loglevel,
364 $tracelevel]|[$level, $callback] )
365 Inherited, see "Error handling" in Mail::Reporter
366
367 $obj->errors()
368 Inherited, see "Error handling" in Mail::Reporter
369
370 $obj->log( [$level, [$strings]] )
371 Mail::Box::POP3->log( [$level, [$strings]] )
372 Inherited, see "Error handling" in Mail::Reporter
373
374 $obj->logPriority($level)
375 Mail::Box::POP3->logPriority($level)
376 Inherited, see "Error handling" in Mail::Reporter
377
378 $obj->logSettings()
379 Inherited, see "Error handling" in Mail::Reporter
380
381 $obj->notImplemented()
382 Inherited, see "Error handling" in Mail::Reporter
383
384 $obj->report( [$level] )
385 Inherited, see "Error handling" in Mail::Reporter
386
387 $obj->reportAll( [$level] )
388 Inherited, see "Error handling" in Mail::Reporter
389
390 $obj->trace( [$level] )
391 Inherited, see "Error handling" in Mail::Reporter
392
393 $obj->warnings()
394 Inherited, see "Error handling" in Mail::Reporter
395
396 Cleanup
397 Extends "Cleanup" in Mail::Box::Net.
398
399 $obj->DESTROY()
400 Inherited, see "Cleanup" in Mail::Box
401
403 Extends "DETAILS" in Mail::Box::Net.
404
405 Different kinds of folders
406 Extends "Different kinds of folders" in Mail::Box::Net.
407
408 Available folder types
409 Extends "Available folder types" in Mail::Box::Net.
410
411 Folder class implementation
412 Extends "Folder class implementation" in Mail::Box::Net.
413
414 How POP3 folders work
415 Rfc1939 defines how POP3 works. POP3 is a really simple protocol to
416 receive messages from a server to a user's client. POP3 is also really
417 limited: it can only be used to fetch messages, but has not many ways
418 to limit the amount of network traffic, like the IMAP4 protocol has.
419
420 One POP3 account represents only one folder: there is no way of sub-
421 folders in POP3. POP3 doesn't support writing (except for some message
422 status flags).
423
424 This implementation
425 The protocol specifics are implemented in Mail::Transport::POP3,
426 written by Liz Mattijsen. That module does not use any of the other
427 POP3 modules available on CPAN for the reason that MailBox tries to be
428 smarter: it is capable of re-establishing broken POP3 connection when
429 the server supports UIDs.
430
431 The implementation has shown to work with many different POP servers.
432 In the test directory of the distribution, you will find a small server
433 implementation, which is used to test the client.
434
436 Error: Cannot create POP3 client for $name.
437 The connection to the POP3 server cannot be established. You may
438 see more, related, error messages about the failure.
439
440 Error: Cannot find head back for $uidl on POP3 server $name.
441 The server told to have this message, but when asked for its
442 headers, no single line was returned. Did the message get
443 destroyed?
444
445 Error: Cannot read body for $uidl on POP3 server $name.
446 The message's headers are retrieved from the server, but the body
447 seems to be lost. Did the message get destroyed between reading
448 the header and reading the body?
449
450 Warning: Changes not written to read-only folder $self.
451 You have opened the folder read-only --which is the default set by
452 new(access)--, made modifications, and now want to close it. Set
453 close(force) if you want to overrule the access mode, or close the
454 folder with close(write) set to "NEVER".
455
456 Error: Copying failed for one message.
457 For some reason, for instance disc full, removed by external
458 process, or read-protection, it is impossible to copy one of the
459 messages. Copying will proceed for the other messages.
460
461 Error: Destination folder $name is not writable.
462 The folder where the messages are copied to is not opened with
463 write access (see new(access)). This has no relation with write
464 permission to the folder which is controlled by your operating
465 system.
466
467 Warning: Different messages with id $msgid
468 The message id is discovered more than once within the same folder,
469 but the content of the message seems to be different. This should
470 not be possible: each message must be unique.
471
472 Error: Folder $name is opened read-only
473 You can not write to this folder unless you have opened the folder
474 to write or append with new(access), or the "force" option is set
475 true.
476
477 Error: Invalid timespan '$timespan' specified.
478 The string does not follow the strict rules of the time span syntax
479 which is permitted as parameter.
480
481 Warning: Message $uidl on POP3 server $name disappeared.
482 The server indicated the existence of this message before, however
483 it has no information about the message anymore.
484
485 Warning: Message-id '$msgid' does not contain a domain.
486 According to the RFCs, message-ids need to contain a unique random
487 part, then an "@", and then a domain name. This is made to avoid
488 the creation of two messages with the same id. The warning emerges
489 when the "@" is missing from the string.
490
491 Warning: POP3 folders cannot be deleted.
492 Each user has only one POP3 folder on a server. This folder is
493 created and deleted by the server's administrator only.
494
495 Error: Package $package does not implement $method.
496 Fatal error: the specific package (or one of its superclasses) does
497 not implement this method where it should. This message means that
498 some other related classes do implement this method however the
499 class at hand does not. Probably you should investigate this and
500 probably inform the author of the package.
501
502 Error: Unable to create subfolder $name of $folder.
503 The copy includes the subfolders, but for some reason it was not
504 possible to copy one of these. Copying will proceed for all other
505 sub-folders.
506
507 Error: Update of $nr messages ignored for POP3 folder $name.
508 The standard POP3 implementation does not support writing from
509 client back to the server. Therefore, modifications may be lost.
510
511 Error: Writing folder $name failed
512 For some reason (you probably got more error messages about this
513 problem) it is impossible to write the folder, although you should
514 because there were changes made.
515
516 Error: You cannot write a message to a pop server (yet)
517 Some extensions to the POP3 protocol do permit writing messages to
518 the server, but the standard protocol only implements retreival.
519 Feel invited to extend our implementation with writing.
520
522 This module is part of Mail-Box-POP3 distribution version 3.005, built
523 on May 03, 2019. Website: http://perl.overmeer.net/CPAN/
524
526 Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
527 ChangeLog.
528
529 This program is free software; you can redistribute it and/or modify it
530 under the same terms as Perl itself. See http://dev.perl.org/licenses/
531
532
533
534perl v5.30.1 2020-01-30 Mail::Box::POP3(3)