Provided by: claws-mail-perl-filter_4.2.0-2build7_amd64 
NAME
cm_perl -- A Perl Plugin for Claws Mail
DESCRIPTION
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.
QUICK START
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.
USAGE
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.
FUNCTION LISTING
For a detailed function description, see section "FUNCTION DESCRIPTIONS", below.
Standard Filtering Conditions
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
Standard Filtering Actions
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
Fun stuff
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
FUNCTION DESCRIPTIONS
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.
Standard Filtering Conditions
all Returns a true value. Available for completeness only.
marked Returns a true value if the marked flag is set, false otherwise.
unread Returns a true value if the unread flag is set, false otherwise.
deleted Returns a true value if the deleted flag is set, false otherwise.
new Returns a true value if the new flag is set, false otherwise.
replied Returns a true value if the replied flag is set, false otherwise.
forwarded
Returns a true value if the forwarded flag is set, false otherwise.
locked Returns a true value if the locked flag is set, false otherwise.
ignore_thread
Returns a true value if the "Ignore Thread" flag is set, false otherwise.
colorlabel COLOR
colorlabel
Returns a true value if message has the color COLOR. COLOR can be either a numeric
value between 0 and 7 (with colors corresponding to the internal filtering
engine), or the english color name as it is introduced in the filtering dialog
(that is, one of: none, orange, red, pink, sky blue, blue, green or brown, while
upper and lower case letters make no difference). If COLOR is omitted, 0 (none) is
assumed.
size_greater SIZE
Returns a true value if message size is greater than SIZE, false otherwise.
size_smaller SIZE
Returns a true value if message size is smaller than SIZE, false otherwise.
size_equal SIZE
Returns a true value if message size is equal to SIZE, false otherwise.
score_greater SCORE
Returns a true value if message score is greater than SCORE, false otherwise.
score_lower SCORE
Returns a true value if message score is lower than SCORE, false otherwise.
score_equal SCORE
Returns a true value if message score is equal to SCORE, false otherwise.
age_greater AGE
Returns a true value if message age is greater than AGE, false otherwise.
age_lower AGE
Returns a true value if message age is lower than AGE, false otherwise.
partial Returns a true value if message has only partially been downloaded, false
otherwise.
tagged Returns a true value if the messages has one or more tags.
test Corresponds the 'test' internal filtering rule. In particular, it accepts the same
symbols, namely:
%% %
%s Subject
%f From
%t To
%c Cc
%d Date
%i Message-ID
%n Newsgroups
%r References
%F Filename -- should not be modified
match WHERE WHAT
matchcase WHERE WHAT
regexp WHERE WHAT
regexpcase WHERE WHAT
The matching functions have a special syntax. The first argument is either any of
to_or_cc, body_part, headers_part, headers_cont, message, to, from, subject, cc,
newsgroups, inreplyto, references, or tag (those strings may or may not be
quoted), the pattern matching works on that area. If it is any other string (which
must then be quoted), this string is taken to be the name of a header field.
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.
Standard Filtering Actions
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)
mark Mark the message.
unmark Unmark the message.
dele Delete the message. Note the name change of Claws Mail' "delete" to "dele". This
is because "delete" is one of Perl's builtin commands which cannot be redefined
(if it can, tell me how).
This is a final rule.
mark_as_read
Mark the message as read
mark_as_unread
Mark the message as unread
lock Lock the message
unlock Remove the message lock
move DESTINATION
Move the message to folder DESTINATION. The folder notation is the same that Claws
Mail uses. You can copy & paste from the move dialog of the normal filtering,
until you get a feeling for the notation.
This is a final rule.
copy DESTINATION
Copy the message to folder DESTINATION. The folder notation is the same that Claws
Mail uses. You can copy & paste from the move dialog of the normal filtering,
until you get a feeling for the notation.
execute COMMAND
This is the same as the test - rule from section "Standard Filtering Conditions"
execpt that it always returns a true value.
hide Hide the message
set_score SCORE
Set message score to SCORE
change_score SCORE
Change message score by SCORE
stop Stop Perl script at this point. Note that this is not a final rule, meaning that
the email gets passed on to the internal filtering engine. See "abort" below if
you don't want that.
forward ACCOUNT, EMAIL
Forward the message to email address EMAIL, using the account ID ACCOUNT as sender
account. So far, you have to create a rule in the normal filtering engine to find
out that number.
forward_as_attachment, ACCOUNT EMAIL
Forward the message to email address EMAIL in an attachment, using the account ID
ACCOUNT as sender account. So far, you have to create a rule in the normal
filtering engine to find out that number.
redirect ACCOUNT, EMAIL
Redirect the message to EMAIL, using the account ID ACCOUNT as sender account. So
far, you have to create a rule in the normal filtering engine to find out that
number.
set_tag TAG
Apply tag TAG. TAG must exist.
unset_tag TAG
Unset tag TAG.
clear_tags
Clear all tags.
Fun stuff
Functions
header ARG
header If ARG is not given, returns a list of all header field names of the mail.
If ARG is given, returns 'undef' if the header field ARG does not exist in the
email. Otherwise, it returns
in scalar context
The value of the header field ARG.
in list context
A list of all available header field values. This is useful if a header field
occurs more than once in an email (eg the Received - header).
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.
body Returns the email body in a scalar.
filepath
Returns the file and path of the email that is currently filtered (corresponds to
the %F arguemnt in the 'test' rule).
extract_addresses
Extracts email addresses from a string and gives back a list of addresses found.
Currently an email address is found using the regular expression
'[-.+\w]+\@[-.+\w]+'. This will not find all valid email addresses. Feel free to
send me a better regexp.
move_to_trash
Move the email message to default trash folder.
This is a final rule.
abort Stop Perl script at this point.
In contrast to 'stop', this is a final rule.
addr_in_addressbook EMAIL, ADDRESSBOOK
addr_in_addressbook EMAIL
Returns a true value if the email address EMAIL is in the addressbook with the
name ADDRESSBOOK. If ADDRESSBOOK is not given, returns true if the email address
is in any addressbook.
from_in_addressbook ADDRESSBOOK
from_in_addressbook
Checks if the email address found in the From-header is in addressbook ADDRESSBOOK
(or any, if omitted). It is implemented as
my ($from) = extract_addresses(header("from"));
return 0 unless $from;
return addr_in_addressbook($from,@_);
so the same restrictions as to extract_addresses apply.
get_attribute_value EMAIL, ATTRIBUTE, ADDRESSBOOK
get_attribute_value EMAIL, ATTRIBUTE
Looks through the addressbook ADDRESSBOOK (or all addressbooks, if omitted) for a
contact with the an email address EMAIL. If found, the function checks if this
contact has a user attribute with name ATTRIBUTE. It returns the value of this
attribute, or an empty string if it was not found. As usual, 'undef' is returned
if an error occurred.
SA_is_spam
Is an alias to
not test 'spamc -c < %F > /dev/null'
exit Has been redefined to be an alias to 'stop'. You shouldn't use Perl's own 'exit'
command, since it would exit Claws Mail.
manual Returns a true value if the filter script was invoked manually, that is, via the
Tools menu.
make_sure_folder_exists IDENTIFIER
Returns a true value if the folder with id IDENTIFIER (e.g. #mh/Mail/foo/bar)
exists or could be created.
make_sure_tag_exists TAG
Returns a true value if the tag TAG exists or could be created.
filter_log SECTION, TEXT
filter_log TEXT
Writes TEXT to the filter logfile. SECTION can be any of
• "LOG_MANUAL"
• "LOG_MATCH"
• "LOG_ACTION"
If the SECTION is omitted, "LOG_MANUAL" is assumed.
filter_log_verbosity VERBOSITY
filter_log_verbosity
Changes the filter log verbosity for the current mail. VERBOSITY must be any of
0 Be silent
1 Log MANUAL type
2 Log Action type
3 Log MATCH type
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
$permanent
This scalar keeps its value between filtered mail messages. On plugin start, it is
initialized to the empty string.
LOGGING
To keep track of what has been done to the mails while filtering, the plugin supports
logging. Three verbosity levels are recognized:
0 logging disabled
1 log only manual messages, that is, messages introduced by the "filter_log" command in
filter scripts
2 log manual messages and filter actions
3 log manual messages, filter actions and filter matches
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.
EXAMPLE
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<----------------------------------------------------
BUGS
• Do not use this plugin together with other filtering plugins, especially the
Spamassassin and ClamAV plugins. They are registered on the same hook and the order in
which the plugins are executed is not guaranteed.
• The filter script is not (yet) updated automatically when a folder gets renamed. The
same applies for folder names in addressbook user attributes.
• This plugin has only be tested with POP3 accounts. If you have experiences with IMAP
or newsgroup accounts, drop me a message.
• Warning during compile time:
*** 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.
LICENSE and (no) WARRANTY
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/.
SEE ALSO
claws-mail(1), perl(1)
AUTHOR
Holger Berndt <berndth@gmx.de>