delete_message

  delete_message from     => 'folder_name',
                 with     => 'My::Delete::Package',
                 matching => sub { return_true_for_delete() };

"from" is a required parameter, a string containing the folder name to delete from. By default "Email::FolderType" is used to determine what package to use when deleting a message. To override the default, specify the "with" parameter. Your package's "delete_message" function will be called with the same arguments that "delete_message" from Email::Delete is called with.

"matching" is a required argument. Its value is a code reference. If the anonymouse subroutine returns a true value, the current message is deleted. Each message is passed to the "matching" test in turn. The first and only argument to "matching" is an "Email::Simple" object representing the message.

If you should ever want to stop processing a mailbox, just call "die" from your code reference. A proper deleting package will not delete mail until all the messages have been scanned. So if you throw an exception, your mail will be preserved and scanning will be aborted.