afew

NAME

afew - afew Documentation afew is an initial tagging script for notmuch mail:
Its basic task is to provide automatic tagging each time new mail is registered with notmuch. In a classic setup, you might call it after notmuch new in an offlineimap post sync hook or in the notmuch post-new hook. It can do basic thing such as adding tags based on email headers or maildir folders, handling killed threads and spam. fyi: afew plays nicely with alot, a GUI for notmuch mail ;)
Contents:

COMMAND LINE USAGE

Ultimately afew is a command line tool. You have to specify an action, and whether to act on all messages, or only on new messages. The actions you can choose from are:

Initial tagging

Basic tagging stuff requires no configuration, just run
To do this automatically you can add the following hook into your ~/.offlineimaprc:
There is a lot more to say about general filter Configuration and the different Filters provided by afew.

Simulation

Adding --dry-run to any --tag or --sync-tags action prevents modification of the notmuch db. Add some -vv goodness to see some action.

Move Mode

To invoke afew in move mode, provide the --move-mails option on the command line. Move mode will respect --dry-run, so throw in --verbose and watch what effects a real run would have. In move mode, afew will check all mails (or only recent ones) in the configured maildir folders, deciding whether they should be moved to another folder. The decision is based on rules defined in your config file. A rule is bound to a source folder and specifies a target folder into which a mail will be moved that is matched by an associated query. This way you will be able to transfer your sorting principles roughly to the classic folder based maildir structure understood by your traditional mail server. Tag your mails with notmuch, call afew --move-mails in an offlineimap presynchook and enjoy a clean inbox in your webinterface/GUI-client at work. Note that in move mode, afew calls notmuch new after moving mails around. You can use afew -m --notmuch-args=--no-hooks in a pre-new notmuch hook to avoid loops. For information on how to configure rules for move mode, what you can do with it and what you can't, please refer to Move Mode.

Commandline help

The full set of options is:

CONFIGURATION

Configuration File

Customization of tag filters takes place in afew's config file in ~/.config/afew/config.

NotMuch Config

afew tries to adapt to the new tag that notmuch sets on new email, but has mostly been developed and used against the new tag. To use that, make sure that ~/.notmuch-config contains:
afew reads the notmuch database location from notmuch config. When no database path is set in notmuch config, afew uses the MAILDIR environment variable when set, or $HOME/mail as a fallback, like notmuch CLI does. If a relative path is provided, afew prepends $HOME/ to the path in the same manner as notmuch, which was introduced in version 0.28 of notmuch.

Filter Configuration

You can modify filters, and define your own versions of the base Filter that allow you to tag messages in a similar way to the notmuch tag command, using the config file. The default config file is:
See the Filters page for the details of those filters and the custom arguments they accept. You can add filters based on the base filter as well. These can be customised by specifying settings beneath them. The standard settings, which apply to all filters, are:
So to add the deer tag to any message to or from [email protected] you could do:
You can also (in combination with the InboxFilter) have email skip the Inbox by removing the new tag before you get to the InboxFilter:

Full Sample Config

Showing some sample configs is the easiest way to understand. The notmuch initial tagging page shows a sample config:
The (roughly) equivalent set up in afew would be:
Not that the queries do not generally include tag:new because this is implied when afew is run with the --new flag. The differences between them is that

More Filter Examples

Here are a few more example filters from github dotfiles:

FILTERS

The default filter set (if you don't specify anything in the config) is:
The standard filter Configuration can be applied to these filters as well. Though note that most of the filters below set their own value for message, query and/or tags, and some ignore some of the standard settings.

ArchiveSentMailsFilter

It extends SentMailsFilter with the following feature:

DKIMValidityFilter

This filter verifies DKIM signatures of E-Mails with DKIM header, and adds dkin-ok or dkin-fail tags.

DMARCReportInspectionFilter

DMARC reports usually come in ZIP files. To check the report you have to unpack and search thru XML document which is very tedious. This filter tags the message as follows: if there's any SPF failure in any attachment, tag the message with "dmarc-spf-fail" tag, otherwise tag with "dmarc-spf-ok" if there's any DKIM failure in any attachment, tag the message with "dmarc-dkim-fail" tag, otherwise tag with "dmarc-dkim-ok"

FolderNameFilter

For each email, it looks at all folders it is in, and uses the path and filename as a tag, for the email. So if you have a procmail or sieve set up that puts emails in folders for you, this might be useful.









the mails in your afew folder will be tagged with 'devel' and 'afew'. If instead your hierarchy is split by a more conventional '/' or any other divider
you need to configure that divider to have your mails properly tagged:

HeaderMatchingFilter

This filter adds tags to a message if the named header matches the regular expression given. The tags can be set, or based on the match. The settings you can use are:
If you surround a tag with {} then it will be replaced with the named match. Some examples are:
SpamFilter and ListMailsFilter are implemented using HeaderMatchingFilter, and are only slightly more complicated than the above examples.

InboxFilter

This removes the new tag, and adds the inbox tag, to any message that isn't killed or spam. (The new tags are set in your notmuch config, and default to just new.)

KillThreadsFilter

If the new message has been added to a thread that has already been tagged killed then add the killed tag to this message. This allows for ignoring all replies to a particular thread.

ListMailsFilter

This filter looks for the List-Id header, and if it finds it, adds a tag lists and a tag named lists/<list-id>.

MeFilter

Add filter tagging mail sent directly to any of addresses defined in Notmuch config file: primary_email or other_email. Default tag is to-me and can be customized with me_tag option.

SentMailsFilter

The settings you can use are:

SpamFilter

The settings you can use are:

Email will be considered spam if the header X-Spam-Flag is present.

Customizing filters

To customize these filters, there are basically two different possibilities: Let's say you like the SpamFilter, but it is way too polite

The index is required if you want to create a new SpamFilter in addition to the default one. If you need just one customized SpamFilter, you can drop the index and customize the default instance.

and create an object or two
You can provide your own filter implementations too. You have to register your filters via entry points. See the afew setup.py for examples on how to register your filters. To add your filters, you just need to install your package in the context of the afew application.

MOVE MODE

Configuration Section

Here is a full sample configuration for move mode:
Below we explain what each bit of this means.

Rules

First you need to specify which folders should be checked for mails that are to be moved (as a whitespace separated list). Folder names containing whitespace need to be quoted:
Then you have to specify rules that define move actions of the form
Every mail in the <src> folder that matches a <qry> will be moved into the <dst> folder associated with that query. A message that matches multiple queries will be copied to multiple destinations. You can bind as many rules to a maildir folder as you deem necessary. Just add them as elements of a (whitespace separated) list. Please note, though, that you need to specify at least one rule for every folder given by the folders option and at least one folder to check in order to use the move mode.
will bind one rule to the maildir folder INBOX that states that all mails in said folder that carry (potentially among others) the tag spam are to be moved into the folder Junk. With <qry> being an arbitrary notmuch query, you have the power to construct arbitrarily flexible rules. You can check for the absence of tags and look out for combinations of attributes:
The above rules will move all mails in Junk that don't have the spam tag but do have an inbox tag into the directory INBOX. All other mails not tagged with spam will be moved into Archive.

Max Age

You can limit the age of mails you want to move by setting the max_age option in the configuration section. By providing
afew will only check mails at most 15 days old.

Rename

Set this option if you are using the mbsync IMAP syncing tool. mbsync adds a unique identifier to files' names when it syncs them. If the rename option is not set, moving files can cause UID conflicts and prevent mbsync from syncing with error messages such as "Maildir error: duplicate UID 1234" or "UID 567 is beyond highest assigned UID 89". When the option is set, afew will rename files while moving them, removing the UID but preserving other mbsync information. This allows mbsync to assign a new UID to the file and avoid UID conflicts. If you are using offlineimap, you can safely ignore this option.

Limitations

(1) Rules don't manipulate tags.
The above combination of rules might prove tricky, since you might expect de-spammed mails to end up in INBOX. But since the Junk rule will not add an inbox tag, the next run in move mode might very well move the matching mails into Archive. Then again, if you remove the spam tag and do not set an inbox tag, how would you come to expect the mail would end up in your INBOX folder after moving it? ;) (2) There is no 1:1 mapping between folders and tags. And that's a feature. If you tag a mail with two tags and there is a rule for each of them, both rules will apply. Your mail will be copied into two destination folders, then removed from its original location.

EXTENDING AFEW

You can put python files in ~/.config/afew/ and they will be imported by afew. If you use that python file to define a Filter class and use the register_filter decorator then you can refer to it in your filter configuration. So an example small filter you could add might be:
We have defined the message and query class variables that are used by the parent class Filter. The message is printed when running with verbose flags. The query is used to select messages to run against - here we ensure we don't bother looking at messages we've already looked at. The handle_message() method is the key one to implement. This will be called for each message that matches the query. The argument is a notmuch message object and the key methods used by the afew filters are get_header(), get_filename() and get_thread(). Of the methods inherited from the Filter class the key ones are add_tags() and remove_tags(), but read about the Implementation or just read the source code to get your own ideas. Once you've defined your filter, you can add it to your config like any other filter:

IMPLEMENTATION

Database Manager

The design of the database manager was inspired by alots database manager alot.db.DBManager.

Filter

Configuration management

Miscellanious utility functions

AUTHOR

Justus Winter

COPYRIGHT

afewmail project