notcoal - notmuch filters, not made from (char)coal
notcoal
provides both a library as well as a standalone binary. The latter can be used as an
"initial tagging" system, the former may be integrated into a bigger e-mail client making use of
notmuch-rs.
What?
Takes regex rules from a JSON file and if any match, either adds new tags, removes tags or runs an arbitrary binaries for further processing. Rules support AND as well as OR operations.
Example
Here the matching expands to:
( from: ("@real.bank" OR "@gig-economy.career") AND subject: ("report" AND "month") )
OR
( from: "no-reply@trusted.bank" AND subject: "statement" )
If if this filter is applied the operations will
- add the tag
€£$
- remove the tags
inbox
andunread
- run the equivalent of
/bin/sh -c 'any-binary-in-our-path-or-absolute-path --argument'
with 3 additional environment variables:
NOTCOAL_FILTER_NAME=money
NOTCOAL_FILE_NAME=/path/to/maildir/new/filename
NOTCOAL_MSG_ID=e81cadebe7dab1cc6fac7e6a41@some-isp
Filters aren't only restricted to matching from
and subject
headers (all of which are treated
case-insensitive) but may try to match arbitrary headers.
Additionally there are the special match fields:
@path
: matches on the full path of a message@tags
: matches on tags already set by previous filters@thread-tags
: matches on tags already present in the message's thread@attachment
: matches on an attachment name@attachment-body
: matches on everytext/plain
attachment's body@body
: matches on the messages body
The default notcoal::filter
function loops through messages and then tests/applies filters in the
order they have been defined in. Hence, any tag one wants to match on has to have been set by a
previous matching rule.
Standalone use for "initial tagging"
To install the standalone helper binary, the simplest way is:
cargo install --locked notcoal --features=standalone
notcoal
will use the same default database as notmuch itself, and the default location for the
rules file is in $notmuchdb/.notmuch/hooks/notcoal-rules.json
. It also expects all newly added
messages (that are to be filtered) to have the new
tag. To make sure that's being set, edit your
.notmuch-config
to include:
[new]
tags=unread;inbox;new;
Additionally, notcoal
will respect the config file's maildir synchronize setting.
See notcoal --help
for supplying alternative values.
If you're fine with the defaults, you can symlink $notmuchdb/.notmuch/hooks/post-new
to the
notcoal
binary.
Thanks
vhdirk for notmuch-rs
, which made this crate possible in the first place, korrat for a patch
for more sensible database discovery, antifuchs' gmail-britta for inspiring the name, and
Recurse Center, for creating a supportive environment 💟