CM_PERL(7) | claws-mail-perl-filter | CM_PERL(7) |
cm_perl -- A Perl Plugin for Claws Mail
This plugin provides an extended filtering engine for the email client Claws Mail. It allows for the use of full Perl power in email filters.
To get started, you can use the matcherrc2perlfilter.pl script in the tools-directory to translate your old filtering rules to Perl. Simply execute the script and follow the instructions. (note that with recent versions of Claws Mail, this script might not work due to upstream syntax changes. This will get updated in the future. Send me an email if you have problems getting started).
However, you might want to consider reading the rest of this manual and rewriting your rules if you choose to use the plugin, since the Perl code produced by this script is not exactly pretty.
Don't speak Perl? No problem, "perldoc perlintro" should give you enough information to do fancy stuff.
The Perl plugin expects a Perl script file called perl_filter in Claws Mail' config directory (usually $HOME/.claws-mail -- try `claws-mail --config-dir' if you're unsure). If that file doesn't exist on plugin start, an empty one is created. This file, which doesn't need to start with a sha-bang (!#/bin/perl), holds the Perl instructions for your email filters. To encourage some good manners, the code is executed in a "use strict;" environment.
Both Claws Mail' filtering conditions and actions are mapped to Perl functions with corresponding names, wherever this is possible.
For a detailed function description, see section "FUNCTION DESCRIPTIONS", below.
all, marked, unread, deleted, new, replied, forwarded, locked, ignore_thread, colorlabel, match, matchcase, regexp, S<regexpcase, test, size_greater, size_smaller, size_equal, score_greater, score_lower, score_equal, age_greater, age_lower, partial, tagged
mark, unmark, dele, mark_as_unread, mark_as_read, lock, unlock, move, copy, color, execute, hide, set_score, change_score, stop, forward, forward_as_attachment, redirect, set_tag, unset_tag, clear_tags
header, body, filepath, extract_addresses, move_to_trash, abort, addr_in_addressbook, from_in_addressbook, get_attribute_value, SA_is_spam, exit, manual, make_sure_folder_exists, filter_log, filter_log_verbosity, make_sure_tag_exists
In general, after the filtering invoked by the Perl script, the mail is passed on to Claws' internal filtering engine, unless a final rule was hit. Final rules stop not only the Perl filtering script at the point of their occurrence, but also prevent processing that email by Claws' internal filtering engine (this might sound confusing, but you are already familiar with that concept from standard filters: After an email was e.g. moved, the following rules don't apply anymore).
Also, be careful with the way you quote. In particular, remember that the @-sign has a special meaning in Perl, and gets interpolated inside double quotes. See "Quote and Quote-like Operators" in perlop to learn more about quoting and interpolation.
The second argument is the string to look for. For match, matchcase, regexp and regexpcase we have case sensitive normal matching, case insensitive normal matching, case sensitive regular expression matching and case insensitive regular expression pattern matching, respectively.
The functions return true if the pattern was found, false otherwise.
Just as with the built-in filtering engine, the message body is searched and provided as is - no character-set analysis is done. Likewise, no HTML-tags are stripped. It should be possible to use external modules or programs for these tasks though. If you're doing that, drop me a message with your experiences.
With Perl having its strengths in pattern matching, using Perl's builtin operators are usually a better option than using these functions.
The actions return a true value upon success, and 'undef' when an error occurred. Final message rules are indicated. (See above for a sketch what a final rule is)
This is a final rule.
This is a final rule.
Functions
If ARG is given, returns 'undef' if the header field ARG does not exist in the email. Otherwise, it returns
The header field "References" forms a special case. In a scalar context, it returns the first reference. In a list context, it returns a list of all references.
This is a final rule.
In contrast to 'stop', this is a final rule.
my ($from) = extract_addresses(header("from")); return 0 unless $from; return addr_in_addressbook($from,@_);
so the same restrictions as to extract_addresses apply.
not test 'spamc -c < %F > /dev/null'
If the SECTION is omitted, "LOG_MANUAL" is assumed.
For the meaning of those numbers, read section "LOGGING". If VERBOSITY is omitted, the filter logfile verbosity is not changed.
This function returns the filter_log_verbosity number before the change (if any).
Variables
To keep track of what has been done to the mails while filtering, the plugin supports logging. Three verbosity levels are recognized:
The messages are logged in Claws Mail' log window. The default log level is 2. Log level 3 is not recommended, because the matcher functions log a message if they succeeded, and thus, if you have negative checks, you'll get confusing entries. If you want to keep track of matching, do it manually, using "filter_log", or do it by temporary enabling matcher logging using "filter_log_verbosity".
The first time you unload this plugin (or shut down Claws Mail), a section called [PerlPlugin] will be created in Claws Mail' configuration file clawsrc, containing one variable:
* filter_log_verbosity
If you want to change the default behaviour, you can edit this line. Make sure Claws Mail is not running while you do this.
It will be possible to access these setting via the GUI, as soon as I find the time to write a corresponding GTK plugin, or somebody else is interested in contributing that.
This section lists a small example of a Perl script file. I'm sure you get the idea..
#-8<---------------------------------------------------- # -*- perl -*- # local functions # Learn ham messages, and move them to specified folder. This is # useful for making sure a bayes filter sees ham as well. sub learn_and_move { execute('put command to learn ham here'); move(@_); } # Two-stage spam filter. Every email that scores higher than 15 # on SpamAssassin gets moved into the default trash folder. # All mails lower than that, but higher than SpamAssassin's # 'required_hits' go into #mh/mail/Spam. sub spamcheck { my $surely_spam = 15; my $filepath = filepath; my $spamc = `spamc -c < $filepath`; my ($value,$threshold) = ($spamc =~ m|([-.,0-9]+)/([-.,0-9]+)|); if($value >= $surely_spam) { mark_as_read; move_to_trash; } if($value >= $threshold) {mark_as_read; move '#mh/mail/Spam';} } # Perl script execution starts here. # Some specific sorting learn_and_move '#mh/mail/MailLists/Claws Mail/user' if matchcase('sender','claws-mail-users-admin@lists.sourceforge.net'); learn_and_move '#mh/mail/MailLists/Sylpheed' if matchcase('list-id','sylpheed.good-day.net'); # Implement incoming folders using addressbook # attributes. Target folders for specific email addresses are # stored directly in the addressbook. This way, if an email # address changes, we only have to update the addressbook, not # the filter rules! Besides that, we can greatly unclutter the # filter script. # get the email address in the from header my $fromheader = header "from"; my ($from) = extract_addresses $fromheader; # check if this email address has an associated attribute # called "incoming_folder". If if has, the value of this # attribute is supposed to be the target folder. my $value = get_attribute_value $from, "incoming_folder"; learn_and_move($value) if $value; # An example of a whitelist: If the from-address is in my # "office" addressbook, move the mail to folder #mh/mail/office learn_and_move '#mh/mail/office' if from_in_addressbook("office"); # If the from-address is in any other addressbook, move the # mail to folder #mh/mail/inbox/known learn_and_move '#mh/mail/inbox/known' if from_in_addressbook; # Feed the remaining mails through SpamAssassin. spamcheck; # mails that make it to the end of the script are passed on to # the internal filtering engine. If the internal rules don't say # otherwise, the mails end up in the default inbox. #-8<----------------------------------------------------
*** Warning: Linking the shared library perl_plugin.la against the *** static library /usr/lib/perl5/5.8.3/i586-linux-thread-multi/auto/DynaLoader/DynaLoader.a is not portable!
Ideas to solve this one are welcome :-)
Please report comments, suggestions and bugreports to the address given in the "AUTHOR" section of this document.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
Holger Berndt <berndth@gmx.de>
2023-01-03 | 4.1.1-2+b1 |