1Mail::Box::IMAP4(3) User Contributed Perl Documentation Mail::Box::IMAP4(3)
2
6 Mail::Box::IMAP4 - handle IMAP4 folders as client
7
9 Mail::Box::IMAP4
10 is a Mail::Box::Net
11 is a Mail::Box
12 is a Mail::Reporter
13
15 use Mail::Box::IMAP4;
16 my $folder = Mail::Box::IMAP4->new(folder => $ENV{MAIL}, ...);
17
19 Maintain a folder which has its messages stored on a remote server.
20 The communication between the client application and the server is
21 implemented using the IMAP4 protocol. See also Mail::Server::IMAP4.
22 This class uses Mail::Transport::IMAP4 to hide the transport of
24 information, and focusses solely on the correct handling of messages
25 within a IMAP4 folder. More than one IMAP4 folder can be handled by
26 one single IMAP4 connection.
27 Extends "DESCRIPTION" in Mail::Box::Net.
29
31 Extends "OVERLOADED" in Mail::Box::Net.
32 overload: ""
34 Inherited, see "OVERLOADED" in Mail::Box
35 overload: @{}
37 Inherited, see "OVERLOADED" in Mail::Box
38 overload: cmp
40 Inherited, see "OVERLOADED" in Mail::Box
41
43 Extends "METHODS" in Mail::Box::Net.
44 Constructors
46 Extends "Constructors" in Mail::Box::Net.
47 Mail::Box::IMAP4->new(%options)
49 The "new" can have many %options. Not only the ones listed here
50 below, but also all the %options for Mail::Transport::IMAP4::new()
51 can be passed.
52 The default depends on the value of new(cache_head).
54 Without folder name, no folder is selected. Only few methods are
56 available now, for instance listSubFolders() to get the top-level
57 folder names. Usually, the folder named "INBOX" will be present.
58 -Option --Defined in --Default
60 access Mail::Box 'r'
61 body_delayed_type Mail::Box Mail::Message::Body::Delayed
62 body_type Mail::Box Mail::Message::Body::Lines
63 cache_body NO
64 cache_head NO or DELAY
65 cache_labels NO or DELAY
66 coerce_options Mail::Box []
67 create Mail::Box <false>
68 extract Mail::Box 10240
69 field_type Mail::Box undef
70 fix_headers Mail::Box <false>
71 folder Mail::Box /
72 folderdir Mail::Box <network location>
73 head_delayed_type Mail::Box Mail::Message::Head::Delayed
74 head_type Mail::Box Mail::Box::IMAP4::Head or Mail::Message::Head::Complete
75 join_connection true
76 keep_dups Mail::Box <false>
77 lock_file Mail::Box undef
78 lock_timeout Mail::Box 1 hour
79 lock_type Mail::Box 'NONE'
80 lock_wait Mail::Box 10 seconds
81 locker Mail::Box undef
82 log Mail::Reporter 'WARNINGS'
83 manager Mail::Box undef
84 message_type Mail::Box Mail::Box::IMAP4::Message
85 multipart_type Mail::Box Mail::Message::Body::Multipart
86 password Mail::Box::Net undef
87 remove_when_empty Mail::Box <false>
88 save_on_exit Mail::Box <true>
89 server_name Mail::Box::Net undef
90 server_port Mail::Box::Net 143
91 trace Mail::Reporter 'WARNINGS'
92 transporter Mail::Transport::IMAP4
93 trusted Mail::Box <false>
94 username Mail::Box::Net undef
95 access => MODE
97 body_delayed_type => CLASS
98 body_type => CLASS|CODE
99 cache_body => 'NO'|'YES'|'DELAY'
100 Body objects are immutable, but may still cached or not. In
101 common case, the body of a message is requested via
102 Mail::Message::body() or Mail::Message::decoded(). This returns
103 a handle to a body object. You may decide whether that body
104 object can be reused or not. "NO" means: retrieve the data each
105 time again, "YES" will cache the body data, "DELAY" will send the
106 whole message when the folder is closed.
107 [local cache] [write]
109 NO no no
110 YES yes no
111 DELAY yes yes
112 cache_head => 'NO'|'PARTIAL'|'DELAY'
114 For a read-only folder, "DELAY" is the default, otherwise "NO" is
115 chosen. The four configuration parameter have subtile
116 consequences. To start with a table:
117 [local cache] [write] [default head_type]
119 NO no no Mail::Box::IMAP4::Head
120 PARTIAL yes no Mail::Box::IMAP4::Head
121 DELAY yes yes Mail::Message::Head::Complete
122 The default "head_type" is Mail::Box::IMAP4::Head, the default
124 "cached_head_type" is Mail::Message::Head::Complete.
125 Having a local cache means that a lookup for a field is first
127 done in a local data-structure (which extends
128 Mail::Message::Head::Partial), and only on the remote server if
129 it was not found. This is dangerous, because your locally cached
130 data can be out-of-sync with the server. However, it may give
131 you a nice performance benefit.
132 "DELAY" will always collect the whole header for you. This is
134 required when you want to look for Resent Groups (See
135 Mail::Message::Head::ResentGroup) or other field order dependent
136 header access. A Mail::Message::Head::Delayed will be created
137 first.
138 cache_labels => 'NO'|'WRITE'|'DELAY'
140 When labels from a message are received, these values can be
141 kept. However, this imposes dangers where the server's internal
142 label storage may get out of sync with your data.
143 With "NO", no caching will take place (but the performance will
145 be worse). With "WRITE", all label access will be cached, but
146 written to the server as well. Both "NO" and "WRITE" will update
147 the labels on the served, even when the folder was opened read-
148 only. "DELAY" will not write the changed information to the
149 server, but delay that till the moment that the folder is closed.
150 It only works when the folder is opened read/write or write is
151 enforced.
152 The default is "DELAY" for folders which where opened read-only.
154 This means that you still can force an update with close(write).
155 For folders which are opened read-write, the default is the
156 safeset setting, which is "NO".
157 coerce_options => ARRAY
159 create => BOOLEAN
160 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
161 field_type => CLASS
162 fix_headers => BOOLEAN
163 folder => FOLDERNAME
164 folderdir => DIRECTORY
165 head_delayed_type => CLASS
166 head_type => CLASS
167 join_connection => BOOLEAN
168 Within this Mail::Box::IMAP4 class is registered which
169 transporters are already in use, i.e. which connections to the
170 IMAP server are already in established. When this option is set,
171 multiple folder openings on the same server will try to reuse one
172 connection.
173 keep_dups => BOOLEAN
175 lock_file => FILENAME
176 lock_timeout => SECONDS
177 lock_type => CLASS|STRING|ARRAY
178 lock_wait => SECONDS
179 locker => OBJECT
180 log => LEVEL
181 manager => MANAGER
182 message_type => CLASS
183 multipart_type => CLASS
184 password => STRING
185 remove_when_empty => BOOLEAN
186 save_on_exit => BOOLEAN
187 server_name => HOSTNAME
188 server_port => INTEGER
189 trace => LEVEL
190 transporter => OBJECT|CLASS
191 The name of the CLASS which will interface with the connection.
192 When you implement your own extension to Mail::Transport::IMAP4,
193 you can either specify a fully instantiated transporter OBJECT,
194 or the name of your own CLASS. When an OBJECT is given, most
195 other options will be ignored.
196 trusted => BOOLEAN
198 username => STRING
199 example:
201 my $imap = Mail::Box::IMAP4->new(username => 'myname',
203 password => 'mypassword', server_name => 'imap.xs4all.nl');
204 my $url = 'imap4://user:password@imap.xs4all.nl');
206 my $imap = $mgr->open($url);
207 my $client = Mail::IMAPClient->new(...);
209 my $imap = Mail::Box::IMAP4->new(imap_client => $client);
210 The folder
212 Extends "The folder" in Mail::Box::Net.
213 $obj->addMessage($message, %options)
215 Inherited, see "The folder" in Mail::Box
216 $obj->addMessages(@messages)
218 Inherited, see "The folder" in Mail::Box
219 Mail::Box::IMAP4->appendMessages(%options)
221 Inherited, see "The folder" in Mail::Box
222 $obj->close(%options)
224 Close the folder. In the case of IMAP, more than one folder can
225 use the same connection, therefore, closing a folder does not
226 always close the connection to the server. Only when no folder is
227 using the connection anymore, a logout will be invoked by
228 Mail::Transport::IMAP4::DESTROY()
229 -Option --Defined in --Default
231 force Mail::Box <false>
232 save_deleted Mail::Box false
233 write Mail::Box MODIFIED
234 force => BOOLEAN
236 save_deleted => BOOLEAN
237 write => 'ALWAYS'|'NEVER'|'MODIFIED'
238 $obj->copyTo($folder, %options)
239 Inherited, see "The folder" in Mail::Box
240 $obj->delete(%options)
242 Inherited, see "The folder" in Mail::Box
243 $obj->folderdir( [$directory] )
245 Inherited, see "The folder" in Mail::Box
246 $obj->name()
248 Inherited, see "The folder" in Mail::Box
249 $obj->organization()
251 Inherited, see "The folder" in Mail::Box
252 $obj->size()
254 Inherited, see "The folder" in Mail::Box
255 $obj->type()
257 Inherited, see "The folder" in Mail::Box
258 $obj->update(%options)
260 Inherited, see "The folder" in Mail::Box
261 $obj->url()
263 Inherited, see "The folder" in Mail::Box
264 Folder flags
266 Extends "Folder flags" in Mail::Box::Net.
267 $obj->access()
269 Inherited, see "Folder flags" in Mail::Box
270 $obj->isModified()
272 Inherited, see "Folder flags" in Mail::Box
273 $obj->modified( [BOOLEAN] )
275 Inherited, see "Folder flags" in Mail::Box
276 $obj->writable()
278 Inherited, see "Folder flags" in Mail::Box
279 The messages
281 Extends "The messages" in Mail::Box::Net.
282 $obj->current( [$number|$message|$message_id] )
284 Inherited, see "The messages" in Mail::Box
285 $obj->find($message_id)
287 Inherited, see "The messages" in Mail::Box
288 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
290 Inherited, see "The messages" in Mail::Box
291 $obj->message( $index, [$message] )
293 Inherited, see "The messages" in Mail::Box
294 $obj->messageId( $message_id, [$message] )
296 Inherited, see "The messages" in Mail::Box
297 $obj->messageIds()
299 Inherited, see "The messages" in Mail::Box
300 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
302 !$label|$filter> )
303 Inherited, see "The messages" in Mail::Box
304 $obj->nrMessages(%options)
306 Inherited, see "The messages" in Mail::Box
307 $obj->scanForMessages($message, $message_ids, $timespan, $window)
309 Inherited, see "The messages" in Mail::Box
310 Sub-folders
312 Extends "Sub-folders" in Mail::Box::Net.
313 $obj->listSubFolders(%options)
315 Mail::Box::IMAP4->listSubFolders(%options)
316 Inherited, see "Sub-folders" in Mail::Box
317 $obj->nameOfSubFolder( $subname, [$parentname] )
319 Mail::Box::IMAP4->nameOfSubFolder( $subname, [$parentname] )
320 Inherited, see "Sub-folders" in Mail::Box
321 $obj->openRelatedFolder(%options)
323 Inherited, see "Sub-folders" in Mail::Box
324 $obj->openSubFolder($subname, %options)
326 Inherited, see "Sub-folders" in Mail::Box
327 $obj->topFolderWithMessages()
329 Mail::Box::IMAP4->topFolderWithMessages()
330 Inherited, see "Sub-folders" in Mail::Box
331 Internals
333 Extends "Internals" in Mail::Box::Net.
334 $obj->body( [$body] )
336 $obj->coerce($message, %options)
337 Inherited, see "Internals" in Mail::Box
338 $obj->create($folder, %options)
340 Mail::Box::IMAP4->create($folder, %options)
341 Inherited, see "METHODS" in Mail::Box::Net
342 $obj->createTransporter($class, %options)
344 Create a transporter object (an instance of
345 Mail::Transport::IMAP4), where $class defines the exact object
346 type. As %options, everything which is acceptable to a transporter
347 initiation can be used (see Mail::Transport::IMAP4::new().
348 -Option --Default
350 join_connection true
351 join_connection => BOOLEAN
353 See new(join_connection). When false, the connection will never
354 be shared with other IMAP mail boxes.
355 $obj->determineBodyType($message, $head)
357 Inherited, see "Internals" in Mail::Box
358 $obj->fetch( <$messages|$selection>, $info )
360 Low-level data retreival about one or more messages via IMAP4 from
361 the remote server. Some of this data may differ from the
362 information which is stored in the message objects which are
363 created by MailBox, so you should avoid the use of this method for
364 your own purposes. The IMAP implementation provides some wrappers
365 around this, providing the correct behavior.
366 An ARRAY of $messages may be specified or some message $selection,
368 acceptable to Mail::Box::messages(). Examples of the latter are
369 'ALL', 'DELETED', or "spam" (messages labelled to contain spam).
370 The $info contains one or more attributes as defined by the IMAP
372 protocol. You have to read the full specs of the related RFCs to
373 see these.
374 Mail::Box::IMAP4->foundIn( [$foldername], %options )
376 Inherited, see "Internals" in Mail::Box
377 $obj->getHead($message)
379 Read the header for the specified message from the remote server.
380 "undef" is returned in case the message disappeared.
381 $obj->getHeadAndBody($message)
383 Read all data for the specified message from the remote server.
384 Return head and body of the mesasge as list, or an empty list if
385 the $message disappeared from the server.
386 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
388 Inherited, see "Internals" in Mail::Box
389 $obj->locker()
391 Inherited, see "Internals" in Mail::Box
392 $obj->read(%options)
394 Inherited, see "Internals" in Mail::Box
395 $obj->readMessages(%options)
397 Inherited, see "Internals" in Mail::Box
398 $obj->storeMessage($message)
400 Inherited, see "Internals" in Mail::Box
401 $obj->toBeThreaded($messages)
403 Inherited, see "Internals" in Mail::Box
404 $obj->toBeUnthreaded($messages)
406 Inherited, see "Internals" in Mail::Box
407 $obj->transporter( [$object] )
409 Returns the object which is the interface to the IMAP4 protocol
410 handler. The IMAP4 handler has the current folder selected. When
411 an $object is specified, it is set to be the transporter from that
412 moment on. The $object must extend Mail::Transport::IMAP4.
413 $obj->updateMessages(%options)
415 Inherited, see "Internals" in Mail::Box
416 $obj->write(%options)
418 The IMAP protocol usually writes the data immediately to the remote
419 server, because that's what the protocol wants. However, some
420 options to new() may delay that to boost performance. This method
421 will, when the folder is being closed, write that info after all.
422 -Option --Defined in --Default
424 force Mail::Box <false>
425 save_deleted <false>
426 force => BOOLEAN
428 save_deleted => BOOLEAN
429 You may be able to save the messages which are flagged for
430 deletion now, but they will be removed anyway when the folder is
431 closed.
432 $obj->writeMessages(%options)
434 -Option --Defined in --Default
435 messages Mail::Box <required>
436 transporter <required>
437 messages => ARRAY
439 transporter => OBJECT
440 Other methods
442 Extends "Other methods" in Mail::Box::Net.
443 $obj->timespan2seconds($time)
445 Mail::Box::IMAP4->timespan2seconds($time)
446 Inherited, see "Other methods" in Mail::Box
447 Error handling
449 Extends "Error handling" in Mail::Box::Net.
450 $obj->AUTOLOAD()
452 Inherited, see "Error handling" in Mail::Reporter
453 $obj->addReport($object)
455 Inherited, see "Error handling" in Mail::Reporter
456 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
458 $callback] )
459 Mail::Box::IMAP4->defaultTrace( [$level]|[$loglevel,
460 $tracelevel]|[$level, $callback] )
461 Inherited, see "Error handling" in Mail::Reporter
462 $obj->errors()
464 Inherited, see "Error handling" in Mail::Reporter
465 $obj->log( [$level, [$strings]] )
467 Mail::Box::IMAP4->log( [$level, [$strings]] )
468 Inherited, see "Error handling" in Mail::Reporter
469 $obj->logPriority($level)
471 Mail::Box::IMAP4->logPriority($level)
472 Inherited, see "Error handling" in Mail::Reporter
473 $obj->logSettings()
475 Inherited, see "Error handling" in Mail::Reporter
476 $obj->notImplemented()
478 Inherited, see "Error handling" in Mail::Reporter
479 $obj->report( [$level] )
481 Inherited, see "Error handling" in Mail::Reporter
482 $obj->reportAll( [$level] )
484 Inherited, see "Error handling" in Mail::Reporter
485 $obj->trace( [$level] )
487 Inherited, see "Error handling" in Mail::Reporter
488 $obj->warnings()
490 Inherited, see "Error handling" in Mail::Reporter
491 Cleanup
493 Extends "Cleanup" in Mail::Box::Net.
494 $obj->DESTROY()
496 Inherited, see "Cleanup" in Mail::Box
497
499 Extends "DETAILS" in Mail::Box::Net.
500
502 Warning: Cannot find head back for $uidl in $folder.
503 The header was read before, but now seems empty: the IMAP4 server
504 does not produce the header lines anymore.
505 Warning: Cannot read body for $uidl in $folder.
507 The header of the message was retrieved from the IMAP4 server, but
508 the body is not read, for an unknown reason.
509 Error: Copying failed for one message.
511 For some reason, for instance disc full, removed by external
512 process, or read-protection, it is impossible to copy one of the
513 messages. Copying will proceed for the other messages.
514 Error: Couldn't select IMAP4 folder $name
516 Error: Destination folder $name is not writable.
517 The folder where the messages are copied to is not opened with
518 write access (see new(access)). This has no relation with write
519 permission to the folder which is controlled by your operating
520 system.
521 Warning: Different messages with id $msgid
523 The message id is discovered more than once within the same folder,
524 but the content of the message seems to be different. This should
525 not be possible: each message must be unique.
526 Error: Folder $name not deleted: not writable.
528 The folder must be opened with write access via new(access),
529 otherwise removing it will be refused. So, you may have write-
530 access according to the operating system, but that will not
531 automatically mean that this "delete" method permits you to. The
532 reverse remark is valid as well.
533 Notice: Impossible to keep deleted messages in IMAP
535 Some folder type have a 'deleted' flag which can be stored in the
536 folder to be performed later. The folder keeps that knowledge even
537 when the folder is rewritten. Well, IMAP4 cannot play that trick.
538 Error: Invalid timespan '$timespan' specified.
540 The string does not follow the strict rules of the time span syntax
541 which is permitted as parameter.
542 Warning: Message $uidl disappeared from $folder.
544 Trying to get the specific message from the server, but it appears
545 to be gone.
546 Warning: Message $uidl disappeared from $folder.
548 Trying to get the specific message from the server, but it appears
549 to be gone.
550 Warning: Message-id '$msgid' does not contain a domain.
552 According to the RFCs, message-ids need to contain a unique random
553 part, then an "@", and then a domain name. This is made to avoid
554 the creation of two messages with the same id. The warning emerges
555 when the "@" is missing from the string.
556 Error: No IMAP4 transporter configured
558 Error: Package $package does not implement $method.
559 Fatal error: the specific package (or one of its superclasses) does
560 not implement this method where it should. This message means that
561 some other related classes do implement this method however the
562 class at hand does not. Probably you should investigate this and
563 probably inform the author of the package.
564 Error: Unable to create subfolder $name of $folder.
566 The copy includes the subfolders, but for some reason it was not
567 possible to copy one of these. Copying will proceed for all other
568 sub-folders.
569
571 This module is part of Mail-Box-IMAP4 distribution version 3.003, built
572 on March 04, 2018. Website: http://perl.overmeer.net/CPAN/
573
575 Copyrights 2001-2018 by [Mark Overmeer]. For other contributors see
576 ChangeLog.
577 This program is free software; you can redistribute it and/or modify it
579 under the same terms as Perl itself. See http://dev.perl.org/licenses/
580perl v5.28.0 2018-03-04 Mail::Box::IMAP4(3)