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 Mail::Box::IMAP4 is extended by
15 Mail::Box::IMAP4s
16
18 my $url = 'imap4://user:passwd@host:port/INBOX';
19 my $url = 'imap://user:passwd@host:port/INBOX';
20 use Mail::Box::IMAP4;
22 my $folder = Mail::Box::IMAP4->new(folder => $url, ...);
23 use Mail::Box::Manager;
25 my $mgr = Mail::Box::Manager->new;
26 my $folder = $msg->open($url, retry => 3, interval => 5);
27
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 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 Extends "DESCRIPTION" in Mail::Box::Net.
39
41 Extends "OVERLOADED" in Mail::Box::Net.
42 overload: ""
44 Inherited, see "OVERLOADED" in Mail::Box
45 overload: @{}
47 Inherited, see "OVERLOADED" in Mail::Box
48 overload: cmp
50 Inherited, see "OVERLOADED" in Mail::Box
51
53 Extends "METHODS" in Mail::Box::Net.
54 Constructors
56 Extends "Constructors" in Mail::Box::Net.
57 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 The default depends on the value of new(cache_head).
64 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 -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 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 [local cache] [write]
119 NO no no
120 YES yes no
121 DELAY yes yes
122 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 [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 The default "head_type" is Mail::Box::IMAP4::Head, the default
134 "cached_head_type" is Mail::Message::Head::Complete.
135 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 "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 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 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 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 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 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 trusted => BOOLEAN
208 username => STRING
209 example:
211 my $imap = Mail::Box::IMAP4->new(username => 'myname',
213 password => 'mypassword', server_name => 'imap.xs4all.nl');
214 my $url = 'imap4://user:password@imap.xs4all.nl');
216 my $imap = $mgr->open($url);
217 my $client = Mail::IMAPClient->new(...);
219 my $imap = Mail::Box::IMAP4->new(imap_client => $client);
220 The folder
222 Extends "The folder" in Mail::Box::Net.
223 $obj->addMessage($message, %options)
225 Inherited, see "The folder" in Mail::Box
226 $obj->addMessages(@messages)
228 Inherited, see "The folder" in Mail::Box
229 Mail::Box::IMAP4->appendMessages(%options)
231 Inherited, see "The folder" in Mail::Box
232 $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 -Option --Defined in --Default
241 force Mail::Box <false>
242 save_deleted Mail::Box false
243 write Mail::Box MODIFIED
244 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 $obj->delete(%options)
252 Inherited, see "The folder" in Mail::Box
253 $obj->folderdir( [$directory] )
255 Inherited, see "The folder" in Mail::Box
256 $obj->name()
258 Inherited, see "The folder" in Mail::Box
259 $obj->organization()
261 Inherited, see "The folder" in Mail::Box
262 $obj->size()
264 Inherited, see "The folder" in Mail::Box
265 $obj->type()
267 Inherited, see "The folder" in Mail::Box
268 $obj->update(%options)
270 Inherited, see "The folder" in Mail::Box
271 $obj->url()
273 Inherited, see "The folder" in Mail::Box
274 Folder flags
276 Extends "Folder flags" in Mail::Box::Net.
277 $obj->access()
279 Inherited, see "Folder flags" in Mail::Box
280 $obj->isModified()
282 Inherited, see "Folder flags" in Mail::Box
283 $obj->modified( [BOOLEAN] )
285 Inherited, see "Folder flags" in Mail::Box
286 $obj->writable()
288 Inherited, see "Folder flags" in Mail::Box
289 The messages
291 Extends "The messages" in Mail::Box::Net.
292 $obj->current( [$number|$message|$message_id] )
294 Inherited, see "The messages" in Mail::Box
295 $obj->find($message_id)
297 Inherited, see "The messages" in Mail::Box
298 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
300 Inherited, see "The messages" in Mail::Box
301 $obj->message( $index, [$message] )
303 Inherited, see "The messages" in Mail::Box
304 $obj->messageId( $message_id, [$message] )
306 Inherited, see "The messages" in Mail::Box
307 $obj->messageIds()
309 Inherited, see "The messages" in Mail::Box
310 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
312 !$label|$filter> )
313 Inherited, see "The messages" in Mail::Box
314 $obj->nrMessages(%options)
316 Inherited, see "The messages" in Mail::Box
317 $obj->scanForMessages($message, $message_ids, $timespan, $window)
319 Inherited, see "The messages" in Mail::Box
320 Sub-folders
322 Extends "Sub-folders" in Mail::Box::Net.
323 $obj->listSubFolders(%options)
325 Mail::Box::IMAP4->listSubFolders(%options)
326 Inherited, see "Sub-folders" in Mail::Box
327 $obj->nameOfSubFolder( $subname, [$parentname] )
329 Mail::Box::IMAP4->nameOfSubFolder( $subname, [$parentname] )
330 Inherited, see "Sub-folders" in Mail::Box
331 $obj->openRelatedFolder(%options)
333 Inherited, see "Sub-folders" in Mail::Box
334 $obj->openSubFolder($subname, %options)
336 Inherited, see "Sub-folders" in Mail::Box
337 $obj->topFolderWithMessages()
339 Mail::Box::IMAP4->topFolderWithMessages()
340 Inherited, see "Sub-folders" in Mail::Box
341 Internals
343 Extends "Internals" in Mail::Box::Net.
344 $obj->body( [$body] )
346 $obj->coerce($message, %options)
347 Inherited, see "Internals" in Mail::Box
348 $obj->create($folder, %options)
350 Mail::Box::IMAP4->create($folder, %options)
351 Inherited, see "METHODS" in Mail::Box::Net
352 $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 -Option --Default
360 join_connection true
361 join_connection => BOOLEAN
363 See new(join_connection). When false, the connection will never
364 be shared with other IMAP mail boxes.
365 $obj->determineBodyType($message, $head)
367 Inherited, see "Internals" in Mail::Box
368 $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 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 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 Mail::Box::IMAP4->foundIn( [$foldername], %options )
386 Inherited, see "Internals" in Mail::Box
387 $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 $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 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
398 Inherited, see "Internals" in Mail::Box
399 $obj->locker()
401 Inherited, see "Internals" in Mail::Box
402 $obj->read(%options)
404 Inherited, see "Internals" in Mail::Box
405 $obj->readMessages(%options)
407 Inherited, see "Internals" in Mail::Box
408 $obj->storeMessage($message)
410 Inherited, see "Internals" in Mail::Box
411 $obj->toBeThreaded($messages)
413 Inherited, see "Internals" in Mail::Box
414 $obj->toBeUnthreaded($messages)
416 Inherited, see "Internals" in Mail::Box
417 $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 $obj->updateMessages(%options)
425 Inherited, see "Internals" in Mail::Box
426 $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 -Option --Defined in --Default
434 force Mail::Box <false>
435 save_deleted <false>
436 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 $obj->writeMessages(%options)
444 -Option --Defined in --Default
445 messages Mail::Box <required>
446 transporter <required>
447 messages => ARRAY
449 transporter => OBJECT
450 Other methods
452 Extends "Other methods" in Mail::Box::Net.
453 $obj->timespan2seconds($time)
455 Mail::Box::IMAP4->timespan2seconds($time)
456 Inherited, see "Other methods" in Mail::Box
457 Error handling
459 Extends "Error handling" in Mail::Box::Net.
460 $obj->AUTOLOAD()
462 Inherited, see "Error handling" in Mail::Reporter
463 $obj->addReport($object)
465 Inherited, see "Error handling" in Mail::Reporter
466 $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 $obj->errors()
474 Inherited, see "Error handling" in Mail::Reporter
475 $obj->log( [$level, [$strings]] )
477 Mail::Box::IMAP4->log( [$level, [$strings]] )
478 Inherited, see "Error handling" in Mail::Reporter
479 $obj->logPriority($level)
481 Mail::Box::IMAP4->logPriority($level)
482 Inherited, see "Error handling" in Mail::Reporter
483 $obj->logSettings()
485 Inherited, see "Error handling" in Mail::Reporter
486 $obj->notImplemented()
488 Inherited, see "Error handling" in Mail::Reporter
489 $obj->report( [$level] )
491 Inherited, see "Error handling" in Mail::Reporter
492 $obj->reportAll( [$level] )
494 Inherited, see "Error handling" in Mail::Reporter
495 $obj->trace( [$level] )
497 Inherited, see "Error handling" in Mail::Reporter
498 $obj->warnings()
500 Inherited, see "Error handling" in Mail::Reporter
501 Cleanup
503 Extends "Cleanup" in Mail::Box::Net.
504 $obj->DESTROY()
506 Inherited, see "Cleanup" in Mail::Box
507
509 Extends "DETAILS" in Mail::Box::Net.
510
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 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 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 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 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 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 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 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 Warning: Message $uidl disappeared from $folder.
554 Trying to get the specific message from the server, but it appears
555 to be gone.
556 Warning: Message $uidl disappeared from $folder.
558 Trying to get the specific message from the server, but it appears
559 to be gone.
560 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 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 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
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
585 Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
586 ChangeLog.
587 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/
590perl v5.30.1 2020-01-30 Mail::Box::IMAP4(3)