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

NAME

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

INHERITANCE

9        Mail::Box::IMAP4
10          is a Mail::Box::Net
11          is a Mail::Box
12          is a Mail::Reporter
13
14        Mail::Box::IMAP4 is extended by
15          Mail::Box::IMAP4s
16

SYNOPSIS

18        my $url = 'imap4://user:passwd@host:port/INBOX';
19        my $url = 'imap://user:passwd@host:port/INBOX';
20
21        use Mail::Box::IMAP4;
22        my $folder = Mail::Box::IMAP4->new(folder => $url, ...);
23
24        use Mail::Box::Manager;
25        my $mgr    = Mail::Box::Manager->new;
26        my $folder = $msg->open($url, retry => 3, interval => 5);
27

DESCRIPTION

29       Maintain a folder which has its messages stored on a remote server.
30       The communication between the client application and the server is
31       implemented using the IMAP4 protocol.  See also Mail::Server::IMAP4.
32
33       This class uses Mail::Transport::IMAP4 to hide the transport of
34       information, and focusses solely on the correct handling of messages
35       within a IMAP4 folder.  More than one IMAP4 folder can be handled by
36       one single IMAP4 connection.
37
38       Extends "DESCRIPTION" in Mail::Box::Net.
39

OVERLOADED

41       Extends "OVERLOADED" in Mail::Box::Net.
42
43       overload: ""
44           Inherited, see "OVERLOADED" in Mail::Box
45
46       overload: @{}
47           Inherited, see "OVERLOADED" in Mail::Box
48
49       overload: cmp
50           Inherited, see "OVERLOADED" in Mail::Box
51

METHODS

53       Extends "METHODS" in Mail::Box::Net.
54
55   Constructors
56       Extends "Constructors" in Mail::Box::Net.
57
58       Mail::Box::IMAP4->new(%options)
59           The "new" can have many %options.  Not only the ones listed here
60           below, but also all the %options for Mail::Transport::IMAP4::new()
61           can be passed.
62
63           The default depends on the value of new(cache_head).
64
65           Without folder name, no folder is selected.  Only few methods are
66           available now, for instance listSubFolders() to get the top-level
67           folder names.  Usually, the folder named "INBOX" will be present.
68
69            -Option           --Defined in     --Default
70             access             Mail::Box        'r'
71             body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
72             body_type          Mail::Box        Mail::Message::Body::Lines
73             cache_body                          NO
74             cache_head                          NO or DELAY
75             cache_labels                        NO or DELAY
76             coerce_options     Mail::Box        []
77             create             Mail::Box        <false>
78             extract            Mail::Box        10240
79             field_type         Mail::Box        undef
80             fix_headers        Mail::Box        <false>
81             folder             Mail::Box        /
82             folderdir          Mail::Box        <network location>
83             head_delayed_type  Mail::Box        Mail::Message::Head::Delayed
84             head_type          Mail::Box        Mail::Box::IMAP4::Head or Mail::Message::Head::Complete
85             join_connection                     true
86             keep_dups          Mail::Box        <false>
87             lock_file          Mail::Box        undef
88             lock_timeout       Mail::Box        1 hour
89             lock_type          Mail::Box        'NONE'
90             lock_wait          Mail::Box        10 seconds
91             locker             Mail::Box        undef
92             log                Mail::Reporter   'WARNINGS'
93             manager            Mail::Box        undef
94             message_type       Mail::Box        Mail::Box::IMAP4::Message
95             multipart_type     Mail::Box        Mail::Message::Body::Multipart
96             password           Mail::Box::Net   undef
97             remove_when_empty  Mail::Box        <false>
98             save_on_exit       Mail::Box        <true>
99             server_name        Mail::Box::Net   undef
100             server_port        Mail::Box::Net   143
101             trace              Mail::Reporter   'WARNINGS'
102             transporter                         Mail::Transport::IMAP4
103             trusted            Mail::Box        <false>
104             username           Mail::Box::Net   undef
105
106           access => MODE
107           body_delayed_type => CLASS
108           body_type => CLASS|CODE
109           cache_body => 'NO'|'YES'|'DELAY'
110             Body objects are immutable, but may still cached or not.  In
111             common case, the body of a message is requested via
112             Mail::Message::body() or Mail::Message::decoded().  This returns
113             a handle to a body object.  You may decide whether that body
114             object can be reused or not.  "NO" means: retrieve the data each
115             time again, "YES" will cache the body data, "DELAY" will send the
116             whole message when the folder is closed.
117
118                     [local cache]  [write]
119              NO         no           no
120              YES        yes          no
121              DELAY      yes          yes
122
123           cache_head => 'NO'|'PARTIAL'|'DELAY'
124             For a read-only folder, "DELAY" is the default, otherwise "NO" is
125             chosen.  The four configuration parameter have subtile
126             consequences.  To start with a table:
127
128                     [local cache]  [write]  [default head_type]
129              NO         no           no     Mail::Box::IMAP4::Head
130              PARTIAL    yes          no     Mail::Box::IMAP4::Head
131              DELAY      yes          yes    Mail::Message::Head::Complete
132
133             The default "head_type" is Mail::Box::IMAP4::Head, the default
134             "cached_head_type" is Mail::Message::Head::Complete.
135
136             Having a local cache means that a lookup for a field is first
137             done in a local data-structure (which extends
138             Mail::Message::Head::Partial), and only on the remote server if
139             it was not found.  This is dangerous, because your locally cached
140             data can be out-of-sync with the server.  However, it may give
141             you a nice performance benefit.
142
143             "DELAY" will always collect the whole header for you.  This is
144             required when you want to look for Resent Groups (See
145             Mail::Message::Head::ResentGroup) or other field order dependent
146             header access.  A Mail::Message::Head::Delayed will be created
147             first.
148
149           cache_labels => 'NO'|'WRITE'|'DELAY'
150             When labels from a message are received, these values can be
151             kept. However, this imposes dangers where the server's internal
152             label storage may get out of sync with your data.
153
154             With "NO", no caching will take place (but the performance will
155             be worse). With "WRITE", all label access will be cached, but
156             written to the server as well.  Both "NO" and "WRITE" will update
157             the labels on the served, even when the folder was opened read-
158             only.  "DELAY" will not write the changed information to the
159             server, but delay that till the moment that the folder is closed.
160             It only works when the folder is opened read/write or write is
161             enforced.
162
163             The default is "DELAY" for folders which where opened read-only.
164             This means that you still can force an update with close(write).
165             For folders which are opened read-write, the default is the
166             safeset setting, which is "NO".
167
168           coerce_options => ARRAY
169           create => BOOLEAN
170           extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
171           field_type => CLASS
172           fix_headers => BOOLEAN
173           folder => FOLDERNAME
174           folderdir => DIRECTORY
175           head_delayed_type => CLASS
176           head_type => CLASS
177           join_connection => BOOLEAN
178             Within this Mail::Box::IMAP4 class is registered which
179             transporters are already in use, i.e. which connections to the
180             IMAP server are already in established.  When this option is set,
181             multiple folder openings on the same server will try to reuse one
182             connection.
183
184           keep_dups => BOOLEAN
185           lock_file => FILENAME
186           lock_timeout => SECONDS
187           lock_type => CLASS|STRING|ARRAY
188           lock_wait => SECONDS
189           locker => OBJECT
190           log => LEVEL
191           manager => MANAGER
192           message_type => CLASS
193           multipart_type => CLASS
194           password => STRING
195           remove_when_empty => BOOLEAN
196           save_on_exit => BOOLEAN
197           server_name => HOSTNAME
198           server_port => INTEGER
199           trace => LEVEL
200           transporter => OBJECT|CLASS
201             The name of the CLASS which will interface with the connection.
202             When you implement your own extension to Mail::Transport::IMAP4,
203             you can either specify a fully instantiated transporter OBJECT,
204             or the name of your own CLASS.  When an OBJECT is given, most
205             other options will be ignored.
206
207           trusted => BOOLEAN
208           username => STRING
209
210           example:
211
212            my $imap   = Mail::Box::IMAP4->new(username => 'myname',
213               password => 'mypassword', server_name => 'imap.xs4all.nl');
214
215            my $url    = 'imap4://user:password@imap.xs4all.nl');
216            my $imap   = $mgr->open($url);
217
218            my $client = Mail::IMAPClient->new(...);
219            my $imap   = Mail::Box::IMAP4->new(imap_client => $client);
220
221   The folder
222       Extends "The folder" in Mail::Box::Net.
223
224       $obj->addMessage($message, %options)
225           Inherited, see "The folder" in Mail::Box
226
227       $obj->addMessages(@messages)
228           Inherited, see "The folder" in Mail::Box
229
230       Mail::Box::IMAP4->appendMessages(%options)
231           Inherited, see "The folder" in Mail::Box
232
233       $obj->close(%options)
234           Close the folder.  In the case of IMAP, more than one folder can
235           use the same connection, therefore, closing a folder does not
236           always close the connection to the server.  Only when no folder is
237           using the connection anymore, a logout will be invoked by
238           Mail::Transport::IMAP4::DESTROY()
239
240            -Option      --Defined in     --Default
241             force         Mail::Box        <false>
242             save_deleted  Mail::Box        false
243             write         Mail::Box        MODIFIED
244
245           force => BOOLEAN
246           save_deleted => BOOLEAN
247           write => 'ALWAYS'|'NEVER'|'MODIFIED'
248       $obj->copyTo($folder, %options)
249           Inherited, see "The folder" in Mail::Box
250
251       $obj->delete(%options)
252           Inherited, see "The folder" in Mail::Box
253
254       $obj->folderdir( [$directory] )
255           Inherited, see "The folder" in Mail::Box
256
257       $obj->name()
258           Inherited, see "The folder" in Mail::Box
259
260       $obj->organization()
261           Inherited, see "The folder" in Mail::Box
262
263       $obj->size()
264           Inherited, see "The folder" in Mail::Box
265
266       $obj->type()
267           Inherited, see "The folder" in Mail::Box
268
269       $obj->update(%options)
270           Inherited, see "The folder" in Mail::Box
271
272       $obj->url()
273           Inherited, see "The folder" in Mail::Box
274
275   Folder flags
276       Extends "Folder flags" in Mail::Box::Net.
277
278       $obj->access()
279           Inherited, see "Folder flags" in Mail::Box
280
281       $obj->isModified()
282           Inherited, see "Folder flags" in Mail::Box
283
284       $obj->modified( [BOOLEAN] )
285           Inherited, see "Folder flags" in Mail::Box
286
287       $obj->writable()
288           Inherited, see "Folder flags" in Mail::Box
289
290   The messages
291       Extends "The messages" in Mail::Box::Net.
292
293       $obj->current( [$number|$message|$message_id] )
294           Inherited, see "The messages" in Mail::Box
295
296       $obj->find($message_id)
297           Inherited, see "The messages" in Mail::Box
298
299       $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
300           Inherited, see "The messages" in Mail::Box
301
302       $obj->message( $index, [$message] )
303           Inherited, see "The messages" in Mail::Box
304
305       $obj->messageId( $message_id, [$message] )
306           Inherited, see "The messages" in Mail::Box
307
308       $obj->messageIds()
309           Inherited, see "The messages" in Mail::Box
310
311       $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
312       !$label|$filter> )
313           Inherited, see "The messages" in Mail::Box
314
315       $obj->nrMessages(%options)
316           Inherited, see "The messages" in Mail::Box
317
318       $obj->scanForMessages($message, $message_ids, $timespan, $window)
319           Inherited, see "The messages" in Mail::Box
320
321   Sub-folders
322       Extends "Sub-folders" in Mail::Box::Net.
323
324       $obj->listSubFolders(%options)
325       Mail::Box::IMAP4->listSubFolders(%options)
326           Inherited, see "Sub-folders" in Mail::Box
327
328       $obj->nameOfSubFolder( $subname, [$parentname] )
329       Mail::Box::IMAP4->nameOfSubFolder( $subname, [$parentname] )
330           Inherited, see "Sub-folders" in Mail::Box
331
332       $obj->openRelatedFolder(%options)
333           Inherited, see "Sub-folders" in Mail::Box
334
335       $obj->openSubFolder($subname, %options)
336           Inherited, see "Sub-folders" in Mail::Box
337
338       $obj->topFolderWithMessages()
339       Mail::Box::IMAP4->topFolderWithMessages()
340           Inherited, see "Sub-folders" in Mail::Box
341
342   Internals
343       Extends "Internals" in Mail::Box::Net.
344
345       $obj->body( [$body] )
346       $obj->coerce($message, %options)
347           Inherited, see "Internals" in Mail::Box
348
349       $obj->create($folder, %options)
350       Mail::Box::IMAP4->create($folder, %options)
351           Inherited, see "METHODS" in Mail::Box::Net
352
353       $obj->createTransporter($class, %options)
354           Create a transporter object (an instance of
355           Mail::Transport::IMAP4), where $class defines the exact object
356           type.  As %options, everything which is acceptable to a transporter
357           initiation can be used (see Mail::Transport::IMAP4::new().
358
359            -Option         --Default
360             join_connection  true
361
362           join_connection => BOOLEAN
363             See new(join_connection).  When false, the connection will never
364             be shared with other IMAP mail boxes.
365
366       $obj->determineBodyType($message, $head)
367           Inherited, see "Internals" in Mail::Box
368
369       $obj->fetch( <$messages|$selection>, $info )
370           Low-level data retreival about one or more messages via IMAP4 from
371           the remote server. Some of this data may differ from the
372           information which is stored in the message objects which are
373           created by MailBox, so you should avoid the use of this method for
374           your own purposes.  The IMAP implementation provides some wrappers
375           around this, providing the correct behavior.
376
377           An ARRAY of $messages may be specified or some message $selection,
378           acceptable to Mail::Box::messages().  Examples of the latter are
379           'ALL', 'DELETED', or "spam" (messages labelled to contain spam).
380
381           The $info contains one or more attributes as defined by the IMAP
382           protocol.  You have to read the full specs of the related RFCs to
383           see these.
384
385       Mail::Box::IMAP4->foundIn( [$foldername], %options )
386           Inherited, see "Internals" in Mail::Box
387
388       $obj->getHead($message)
389           Read the header for the specified message from the remote server.
390           "undef" is returned in case the message disappeared.
391
392       $obj->getHeadAndBody($message)
393           Read all data for the specified message from the remote server.
394           Return head and body of the mesasge as list, or an empty list if
395           the $message disappeared from the server.
396
397       $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
398           Inherited, see "Internals" in Mail::Box
399
400       $obj->locker()
401           Inherited, see "Internals" in Mail::Box
402
403       $obj->read(%options)
404           Inherited, see "Internals" in Mail::Box
405
406       $obj->readMessages(%options)
407           Inherited, see "Internals" in Mail::Box
408
409       $obj->storeMessage($message)
410           Inherited, see "Internals" in Mail::Box
411
412       $obj->toBeThreaded($messages)
413           Inherited, see "Internals" in Mail::Box
414
415       $obj->toBeUnthreaded($messages)
416           Inherited, see "Internals" in Mail::Box
417
418       $obj->transporter( [$object] )
419           Returns the object which is the interface to the IMAP4 protocol
420           handler.  The IMAP4 handler has the current folder selected.  When
421           an $object is specified, it is set to be the transporter from that
422           moment on.  The $object must extend Mail::Transport::IMAP4.
423
424       $obj->updateMessages(%options)
425           Inherited, see "Internals" in Mail::Box
426
427       $obj->write(%options)
428           The IMAP protocol usually writes the data immediately to the remote
429           server, because that's what the protocol wants.  However, some
430           options to new() may delay that to boost performance.  This method
431           will, when the folder is being closed, write that info after all.
432
433            -Option      --Defined in     --Default
434             force         Mail::Box        <false>
435             save_deleted                   <false>
436
437           force => BOOLEAN
438           save_deleted => BOOLEAN
439             You may be able to save the messages which are flagged for
440             deletion now, but they will be removed anyway when the folder is
441             closed.
442
443       $obj->writeMessages(%options)
444            -Option     --Defined in     --Default
445             messages     Mail::Box        <required>
446             transporter                   <required>
447
448           messages => ARRAY
449           transporter => OBJECT
450
451   Other methods
452       Extends "Other methods" in Mail::Box::Net.
453
454       $obj->timespan2seconds($time)
455       Mail::Box::IMAP4->timespan2seconds($time)
456           Inherited, see "Other methods" in Mail::Box
457
458   Error handling
459       Extends "Error handling" in Mail::Box::Net.
460
461       $obj->AUTOLOAD()
462           Inherited, see "Error handling" in Mail::Reporter
463
464       $obj->addReport($object)
465           Inherited, see "Error handling" in Mail::Reporter
466
467       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
468       $callback] )
469       Mail::Box::IMAP4->defaultTrace( [$level]|[$loglevel,
470       $tracelevel]|[$level, $callback] )
471           Inherited, see "Error handling" in Mail::Reporter
472
473       $obj->errors()
474           Inherited, see "Error handling" in Mail::Reporter
475
476       $obj->log( [$level, [$strings]] )
477       Mail::Box::IMAP4->log( [$level, [$strings]] )
478           Inherited, see "Error handling" in Mail::Reporter
479
480       $obj->logPriority($level)
481       Mail::Box::IMAP4->logPriority($level)
482           Inherited, see "Error handling" in Mail::Reporter
483
484       $obj->logSettings()
485           Inherited, see "Error handling" in Mail::Reporter
486
487       $obj->notImplemented()
488           Inherited, see "Error handling" in Mail::Reporter
489
490       $obj->report( [$level] )
491           Inherited, see "Error handling" in Mail::Reporter
492
493       $obj->reportAll( [$level] )
494           Inherited, see "Error handling" in Mail::Reporter
495
496       $obj->trace( [$level] )
497           Inherited, see "Error handling" in Mail::Reporter
498
499       $obj->warnings()
500           Inherited, see "Error handling" in Mail::Reporter
501
502   Cleanup
503       Extends "Cleanup" in Mail::Box::Net.
504
505       $obj->DESTROY()
506           Inherited, see "Cleanup" in Mail::Box
507

DETAILS

509       Extends "DETAILS" in Mail::Box::Net.
510

DIAGNOSTICS

512       Warning: Cannot find head back for $uidl in $folder.
513           The header was read before, but now seems empty: the IMAP4 server
514           does not produce the header lines anymore.
515
516       Warning: Cannot read body for $uidl in $folder.
517           The header of the message was retrieved from the IMAP4 server, but
518           the body is not read, for an unknown reason.
519
520       Error: Copying failed for one message.
521           For some reason, for instance disc full, removed by external
522           process, or read-protection, it is impossible to copy one of the
523           messages.  Copying will proceed for the other messages.
524
525       Error: Couldn't select IMAP4 folder $name
526       Error: Destination folder $name is not writable.
527           The folder where the messages are copied to is not opened with
528           write access (see new(access)).  This has no relation with write
529           permission to the folder which is controlled by your operating
530           system.
531
532       Warning: Different messages with id $msgid
533           The message id is discovered more than once within the same folder,
534           but the content of the message seems to be different.  This should
535           not be possible: each message must be unique.
536
537       Error: Folder $name not deleted: not writable.
538           The folder must be opened with write access via new(access),
539           otherwise removing it will be refused.  So, you may have write-
540           access according to the operating system, but that will not
541           automatically mean that this "delete" method permits you to.  The
542           reverse remark is valid as well.
543
544       Notice: Impossible to keep deleted messages in IMAP
545           Some folder type have a 'deleted' flag which can be stored in the
546           folder to be performed later.  The folder keeps that knowledge even
547           when the folder is rewritten.  Well, IMAP4 cannot play that trick.
548
549       Error: Invalid timespan '$timespan' specified.
550           The string does not follow the strict rules of the time span syntax
551           which is permitted as parameter.
552
553       Warning: Message $uidl disappeared from $folder.
554           Trying to get the specific message from the server, but it appears
555           to be gone.
556
557       Warning: Message $uidl disappeared from $folder.
558           Trying to get the specific message from the server, but it appears
559           to be gone.
560
561       Warning: Message-id '$msgid' does not contain a domain.
562           According to the RFCs, message-ids need to contain a unique random
563           part, then an "@", and then a domain name.  This is made to avoid
564           the creation of two messages with the same id.  The warning emerges
565           when the "@" is missing from the string.
566
567       Error: No IMAP4 transporter configured
568       Error: Package $package does not implement $method.
569           Fatal error: the specific package (or one of its superclasses) does
570           not implement this method where it should. This message means that
571           some other related classes do implement this method however the
572           class at hand does not.  Probably you should investigate this and
573           probably inform the author of the package.
574
575       Error: Unable to create subfolder $name of $folder.
576           The copy includes the subfolders, but for some reason it was not
577           possible to copy one of these.  Copying will proceed for all other
578           sub-folders.
579

SEE ALSO

581       This module is part of Mail-Box-IMAP4 distribution version 3.007, built
582       on June 13, 2019. Website: http://perl.overmeer.net/CPAN/
583

LICENSE

585       Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
586       ChangeLog.
587
588       This program is free software; you can redistribute it and/or modify it
589       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
590
591
592
593perl v5.34.0                      2022-01-21               Mail::Box::IMAP4(3)
Impressum