1Mail::Box::POP3(3) User Contributed Perl Documentation Mail::Box::POP3(3)
2
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 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 Extends "DESCRIPTION" in Mail::Box::Net.
30
32 Extends "OVERLOADED" in Mail::Box::Net.
33 overload: ""
35 Inherited, see "OVERLOADED" in Mail::Box
36 overload: @{}
38 Inherited, see "OVERLOADED" in Mail::Box
39 overload: cmp
41 Inherited, see "OVERLOADED" in Mail::Box
42
44 Extends "METHODS" in Mail::Box::Net.
45 Constructors
47 Extends "Constructors" in Mail::Box::Net.
48 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 -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 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 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 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 example:
131 my $url = 'pop3://user:password@pop.xs4all.nl'
133 my $pop = Mail::Box::POP3->new($url);
134 my $pop = $mgr->open(type => 'pop3',
136 username => 'myname', password => 'mypassword',
137 server_name => 'pop.xs4all.nl');
138 The folder
140 Extends "The folder" in Mail::Box::Net.
141 $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 "undef" is returned, and an error displayed. However, no complaint
148 is given when the $message is "undef" itself.
149 -Option--Defined in--Default
151 share Mail::Box <not used>
152 share => BOOLEAN
154 $obj->addMessages($messages)
155 As useless as addMessage(). The only acceptable call to this
156 method is without any message.
157 Mail::Box::POP3->appendMessages(%options)
159 Inherited, see "The folder" in Mail::Box
160 $obj->close(%options)
162 Inherited, see "The folder" in Mail::Box
163 $obj->copyTo($folder, %options)
165 Inherited, see "The folder" in Mail::Box
166 $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 -Option --Defined in--Default
173 recursive Mail::Box <not used>
174 recursive => BOOLEAN
176 $obj->folderdir( [$directory] )
177 Inherited, see "The folder" in Mail::Box
178 $obj->name()
180 Inherited, see "The folder" in Mail::Box
181 $obj->organization()
183 Inherited, see "The folder" in Mail::Box
184 $obj->size()
186 Inherited, see "The folder" in Mail::Box
187 $obj->type()
189 Inherited, see "The folder" in Mail::Box
190 $obj->update()
192 NOT IMPLEMENTED YET
193 $obj->url()
195 Inherited, see "The folder" in Mail::Box
196 Folder flags
198 Extends "Folder flags" in Mail::Box::Net.
199 $obj->access()
201 Inherited, see "Folder flags" in Mail::Box
202 $obj->isModified()
204 Inherited, see "Folder flags" in Mail::Box
205 $obj->modified( [BOOLEAN] )
207 Inherited, see "Folder flags" in Mail::Box
208 $obj->writable()
210 Inherited, see "Folder flags" in Mail::Box
211 The messages
213 Extends "The messages" in Mail::Box::Net.
214 $obj->current( [$number|$message|$message_id] )
216 Inherited, see "The messages" in Mail::Box
217 $obj->find($message_id)
219 Inherited, see "The messages" in Mail::Box
220 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
222 Inherited, see "The messages" in Mail::Box
223 $obj->message( $index, [$message] )
225 Inherited, see "The messages" in Mail::Box
226 $obj->messageId( $message_id, [$message] )
228 Inherited, see "The messages" in Mail::Box
229 $obj->messageIds()
231 Inherited, see "The messages" in Mail::Box
232 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
234 !$label|$filter> )
235 Inherited, see "The messages" in Mail::Box
236 $obj->nrMessages(%options)
238 Inherited, see "The messages" in Mail::Box
239 $obj->scanForMessages($message, $message_ids, $timespan, $window)
241 Inherited, see "The messages" in Mail::Box
242 Sub-folders
244 Extends "Sub-folders" in Mail::Box::Net.
245 $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 -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 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 $obj->openRelatedFolder(%options)
266 Inherited, see "Sub-folders" in Mail::Box
267 $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 $obj->topFolderWithMessages()
274 Mail::Box::POP3->topFolderWithMessages()
275 Inherited, see "Sub-folders" in Mail::Box
276 Internals
278 Extends "Internals" in Mail::Box::Net.
279 $obj->coerce($message, %options)
281 Inherited, see "Internals" in Mail::Box
282 $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 -Option --Defined in--Default
289 folderdir Mail::Box undef
290 folderdir => DIRECTORY
292 $obj->determineBodyType($message, $head)
293 Inherited, see "Internals" in Mail::Box
294 Mail::Box::POP3->foundIn( [$foldername], %options )
296 Inherited, see "Internals" in Mail::Box
297 $obj->getHead($message)
299 Read the header for the specified message from the remote server.
300 $obj->getHeadAndBody($message)
302 Read all data for the specified message from the remote server.
303 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
305 Inherited, see "Internals" in Mail::Box
306 $obj->locker()
308 Inherited, see "Internals" in Mail::Box
309 $obj->popClient(%options)
311 Returns the pop client object. This does not establish the
312 connection.
313 -Option --Default
315 use_ssl <false>
316 use_ssl => BOOLEAN
318 $obj->read(%options)
319 Inherited, see "Internals" in Mail::Box
320 $obj->readMessages(%options)
322 Inherited, see "Internals" in Mail::Box
323 $obj->storeMessage($message)
325 Inherited, see "Internals" in Mail::Box
326 $obj->toBeThreaded($messages)
328 Inherited, see "Internals" in Mail::Box
329 $obj->toBeUnthreaded($messages)
331 Inherited, see "Internals" in Mail::Box
332 $obj->updateMessages(%options)
334 Inherited, see "Internals" in Mail::Box
335 $obj->write(%options)
337 Inherited, see "Internals" in Mail::Box
338 $obj->writeMessages(%options)
340 -Option --Defined in--Default
341 messages Mail::Box <required>
342 messages => ARRAY
344 Other methods
346 Extends "Other methods" in Mail::Box::Net.
347 $obj->timespan2seconds($time)
349 Mail::Box::POP3->timespan2seconds($time)
350 Inherited, see "Other methods" in Mail::Box
351 Error handling
353 Extends "Error handling" in Mail::Box::Net.
354 $obj->AUTOLOAD()
356 Inherited, see "Error handling" in Mail::Reporter
357 $obj->addReport($object)
359 Inherited, see "Error handling" in Mail::Reporter
360 $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 $obj->errors()
368 Inherited, see "Error handling" in Mail::Reporter
369 $obj->log( [$level, [$strings]] )
371 Mail::Box::POP3->log( [$level, [$strings]] )
372 Inherited, see "Error handling" in Mail::Reporter
373 $obj->logPriority($level)
375 Mail::Box::POP3->logPriority($level)
376 Inherited, see "Error handling" in Mail::Reporter
377 $obj->logSettings()
379 Inherited, see "Error handling" in Mail::Reporter
380 $obj->notImplemented()
382 Inherited, see "Error handling" in Mail::Reporter
383 $obj->report( [$level] )
385 Inherited, see "Error handling" in Mail::Reporter
386 $obj->reportAll( [$level] )
388 Inherited, see "Error handling" in Mail::Reporter
389 $obj->trace( [$level] )
391 Inherited, see "Error handling" in Mail::Reporter
392 $obj->warnings()
394 Inherited, see "Error handling" in Mail::Reporter
395 Cleanup
397 Extends "Cleanup" in Mail::Box::Net.
398 $obj->DESTROY()
400 Inherited, see "Cleanup" in Mail::Box
401
403 Extends "DETAILS" in Mail::Box::Net.
404 Different kinds of folders
406 Extends "Different kinds of folders" in Mail::Box::Net.
407 Available folder types
409 Extends "Available folder types" in Mail::Box::Net.
410 Folder class implementation
412 Extends "Folder class implementation" in Mail::Box::Net.
413 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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/
531perl v5.38.0 2023-07-20 Mail::Box::POP3(3)