1Mail::Box::POP3(3)    User Contributed Perl Documentation   Mail::Box::POP3(3)
2
3
4

NAME

6       Mail::Box::POP3 - handle POP3 folders as client
7

INHERITANCE

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

SYNOPSIS

18        use Mail::Box::POP3;
19        my $folder = Mail::Box::POP3->new(folder => $ENV{MAIL}, ...);
20

DESCRIPTION

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

OVERLOADED

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

METHODS

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

DETAILS

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

DIAGNOSTICS

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

SEE ALSO

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

LICENSE

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.34.0                      2021-07-22                Mail::Box::POP3(3)
Impressum