/ 
Mail-ThreadKiller-1.0
River stage zero No dependents
/ Mail::ThreadKiller

NAME

Mail::ThreadKiller - get rid of an entire email thread

SYNOPSIS

use Mail::ThreadKiller;

my $tk = Mail::ThreadKiller->new();
$tk->open_db_file('/path/to/berkeley_db');

# $mail is assumed to be an Email::Simple object
if (whatever_criteria_you_like_to_kill_thread($mail)) {
        $tk->kill_message($mail);
        # And do whatever's needed in your filter to discard mail
}

# Check if this is a followup to a killed thread
if ($tk->should_kill_message($mail)) {
        # Do whatever's needed in your filter to discard mail
}

# Prune the datase - delete message-IDs not seen in 30 days
$tk->clean_db(30);

# Close the DB.  This called automatically if $tk goes out of scope
$tk->close_db_file();

DESCRIPTION

This module is meant to be used within an email filter such as Email::Filter; specifically, it should be used in a filter that is run by a delivery agent so it runs as the particular user whose mail is being filtered---it is not suitable as a milter or any other type of central filter.

Mail::ThreadKiller helps you discard or otherwise redirect entire message threads. The basic idea is as follows:

  • You use whatever criteria you like to detect the beginning of an email thread you'd like to kill. Such criteria could include the subject, the sender, the recipient list, etc. For example, a very common desire is to stop seeing all mail from a troublesome mailing list poster as well as any replies to a thread started by that poster. In this case, your initial criterion could be the troublesome poster's email address in the From: header.

  • Once you've detected the beginning of a thread, you kill the message. You use Mail::ThreadKiller to add the Message-ID to a Berkeley database of IDs; we call this database the persistent database of killed threads or the kill database for short. Then you configure your filter to dispose of the message however you like.

  • For all other messages, you ask Mail::ThreadKiller if any Message-IDs in the Message-ID:, In-Reply-To: or References: headers is in the kill database. If so, Mail::ThreadKiller adds the current Message-ID to the database and returns true; you then dispose of the message according to your policy. If the message does not refer to anything in the database, then Mail::ThreadKiller does nothing and your filter continues processing normally.

  • Periodically, you run the script threadkiller-clean-db.pl to remove very old Message-IDs from the kill database.

METHODS

Mail::ThreadKiller->new()

Create a new Mail::ThreadKiller object

open_db_file('/path/to/berkeley_db')

Opens the kill database. This method must be called before any other methods. Note that you should minimize the code between opening the DB file and closing it because Mail::ThreadKiller obtains an exclusive lock on the file for the duration.

kill_message ( $mail )

$mail is an instance of Email::Simple. This method simply adds the Message-Id: field to the kill database. It returns 0 if the Message-ID is not defined; otherwise non-zero.

add_message_id ( $msgid )

Add the message-ID $msgid to the database of killed threads. This is a low-level internal function used by kill_message, but which may occasionally be useful for external callers.

should_kill_message ( $mail )

$mail is an instance of Email::Simple. It returns non-zero if any of the Message-Ids found in the Message-Id:, In-Reply-To: or References: headers is found in the kill database. Additionally, it adds the Message-Id: of $mail to the kill database.

If none of the Message-Ids was found, returns zero.

clean_db ( $days )

Removes all Message-Ids from the kill database that are older than $days days. Returns the number of entries removed.

close_db_file ( )

Closes the database file. The only method that can be called once this method has been called is open_db_file.

AUTHOR

Dianne Skoll <dfs@roaringpenguin.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Roaring Penguin Software Inc.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

SEE ALSO

threadkiller-clean-db.pl, threadkiller-kill-msgids.pl