Mail::Box::Threads - maintain threads within a folder


Mail::Box::Threads - maintain threads within a folder


   my Mail::Box $folder = ...;
   foreach my $thread ($folder->threads)
   {   $thread->printThread;


Read the Mail::Box::Manager manpage and the Mail::Box manpage first. It might be helpfull to study the Mail::Box::Thread manpage too.

A (message-)thread is a message, with the messages which followed in reply on that message. And the messages with replied the messages which replied the original message. And so on. Some threads are only one message (never replied to), some threads are very long.


new ARGS
An Mail::Box::Threads-object is created by a Mail::Box folder upon creation. The pameters specified here are passed on from the flags at folder creation.

The construction of thread administration accepts the following options:

toBeThreaded MESSAGE [, ...]
toBeUnthreaded MESSAGE-ID [, ...]
Register a message to be put in (withdrawn from) a thread when the user is asking for threads. If no-one ever asks for threads, then no work is done on them.

createDummy MESSAGE-ID
Create a dummy message for this folder. The dummy is a place-holder in a thread description to represent a message which is not found in the folder (yet).

Parse all messages which where detected in the folder, but were not processed into a thread yet.

thread MESSAGE
Based on a message, and facts from previously detected threads, try to build solid knowledge about the thread where this message is in.

inThread MESSAGE
Collect the thread-information of one message. The `In-Reply-To' and `Reference' header-fields are processed. If this method is called on a message whose header was not read yet (as usual for MH-folders, for instance) the reading of that header will be triggered here.


   $message->inThread;    #same

outThread MESSAGE-ID
Remove the message, which is represented by its message-id, from the thread-infrastructure. A message is replaced by a dummy, if it has follow-ups.

Register the message as start of a thread.

Returns all messages which start a thread. The list may contain dummy messages, and messages which are scheduled for deletion.

To be able to return all threads, thread construction on each message is performed first, which may be slow for some folder-types because is will enforce parsing of message-bodies.

Returns the list of all messages which are known to be the start of a thread. Threads containing messages which where not read from their folder (like often happends MH-folder messages) are not yet known, and hence will not be returned.

The list may contain dummy messages, and messages which are scheduled for deletion. Threads are detected based on explicitly calling inThread() and thread() with a messages from the folder.

Be warned that, each time a message's header is read from the folder, the return of the method can change.


This module implements thread-detection on a folder. Messages created by the better mailers will include In-Reply-To and References lines, which are used to figure out how messages are related. If you prefer a better thread detection, then you can ask for it, but there may be a serious performance hit (depends on the type of folder used).

Delayed thread detection

With threads you get the start-messages of each thread of this folder. When that message was not found in the folder (not saved or already removed), you get a message of the dummy-type. These thread descriptions are in perfect state: all messages of the folder are included somewhere, and each missing message of the threads (`holes') are filled by dummies.

However, to be able to detect all threads it is required to have the headers of all messages, which is very slow for some types of folders, especially MH and IMAP folders.

For interactive mail-readers, it is prefered to detect threads only on messages which are in the viewport of the user. This may be sloppy in some situations, but everything is preferable over reading an MH mailbox with 10k e-mails to read only the see most recent messages.

In this object, we take special care not to cause unnecessary parsing (loading) of messages. Threads will only be detected on command, and by default only the message headers are used.

The user of the folder signals that a message has to be included in a thread within the thread-list, by calling

   $folder->inThread($message);   #or

This only takes the information from this message, and stores this in a thread-structure. You can also directly ask for the thread where the message is in:

   my $thread = $message->thread;

When the message was not put in a thread, it is done now. But, more work is done to return the best thread. Based on various parameters, which where specified when the folder was created, the method walks through the folder to fill the holes which are in this thread.

Walking from back to front (latest messages are usually in the back of the folder), message after message are triggered to be indexed in their thread. At a certain moment, the whole thread of the requested method is found, a certain maximum number of messages was tried, but that didn't help (search window bound reached), or the messages within the folder are getting too old. Then the search to complete the thread will end, although more messages of the could be in the folder.

Finally, for each message where the head is known, for instance for all messages in mbox-folders, the correct thread is determined immediately. Also, all messages where the head get loaded later, are automatically included.


Mark Overmeer ( All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


This code is beta, version 1.200

 Mail::Box::Threads - maintain threads within a folder