#notmuch #filter #tagging

bin+lib notcoal

Not charcoal filters, but notmuch ones. Filter library for the notmuch email system

5 unstable releases

✓ Uses Rust 2018 edition

0.3.0 Dec 29, 2018
0.2.6 Dec 14, 2018
0.2.5 Dec 13, 2018
0.2.0 Nov 11, 2018
0.1.0 Nov 6, 2018

#24 in Email

Download history 5/week @ 2018-11-20 6/week @ 2018-11-27 8/week @ 2018-12-04 22/week @ 2018-12-11 33/week @ 2018-12-18 12/week @ 2018-12-25 7/week @ 2019-01-01 16/week @ 2019-01-08 12/week @ 2019-01-15 3/week @ 2019-01-22 2/week @ 2019-01-29 1/week @ 2019-02-12 2/week @ 2019-02-19 10/week @ 2019-02-26

39 downloads per month

GPL-3.0 license

32KB
614 lines

notcoal - notmuch filters, not made from (char)coal

Build status Latest release Docs License

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

[{
    "name": "money",
    "desc": "Money stuff",
    "rules": [
        {"from": "@(real\\.bank|gig-economy\\.career)",
         "subject": ["report", "month" ]},
        {"from": "no-reply@trusted\\.bank",
         "subject": "statement"}
    ],
    "op": {
        "add": "€£$",
        "rm": ["inbox", "unread"],
        "run": ["any-binary-in-our-path-or-absolute-path", "--argument"]
    }
}]

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 and unread
  • 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 every text/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 notcoal --features=standalone

The notcoal binary automatically extracts the location of the notmuch database by reading ~/.notmuch-config. The default location for rules is $maildir/.notmuch/hooks/notcoal-rules.json. By default, it expects all newly added messages (that are to be filtered) to have the new tag. To make sure that's being set, edit the .notmuch-config to include:

[new]
tags=unread;inbox;new;

See notcoal --help for supplying alternative values. However if you're fine with the defaults, you can just symlink $maildir/.notmuch/hooks/post-new to ~/.cargo/bin/notcoal!

Additionally, notcoal will respect the maildir synchronize setting in ~/.notmuch-config as well.

Thanks

vhdirk for notmuch-rs, which made this crate possible in the first place, antifuchs' gmail-britta for inspiring the name, and Recurse Center, for creating a supportive environment 💟

Dependencies

~7MB
~114K SLoC