IMAP mailbox filter

As a standalone mailbox filter tool, imapsrt uses IMAP server-side search filters to sort mails into folders accordingly. This is done without involving other mailreader applications or webservices, thus not requiring any external GUI support.

This the initial and now legacy C++ from-scratch prototype for the Python-based IMAP search reimplementation project.

Common scenarios in which one would want to use an external IMAP filter program could be:

• the mail-client has only limited support for custom filters, or none at all
• the mail provider itself sends spam which cannot be filtered with built-in functionality
• legit mails are flagged as spam before custom rules are evaluated

At least those were the usecases motivating the development of this project. In addition, the dedicated-filter-tool approach comes with the advantage of increased flexibility, unified configuration, and central management.

The mode of operation is rather straight forward: Given a mailbox folder, move all emails that satisfy some search term to another folder. As searching and moving gets solely done at the server-side, there is no overhead for downloading actual mail headers or contents.

Mailbox filter usage

After startup, imapsrt reads its configuration file, connects to the given IMAP server(s), and processes inbox folders one by one.

./imapsrt [--interactive|--batch] [--no-check-certificate] config

Apart from the config file, there are the following optional arguments:

interactive

In this mode, each actual move operation must be user-approved. Also, empty passwords given in the configuration file will be asked for per default.

batch

Don’t prompt for empty passwords or ask for move confirmation. No stalling or user interaction is thus possible.

no-check-certificate

Disables server certificate verification – this option should not be needed when using production IMAP servers! However, for OpenSSL libraries before version 1.0.2 or when -DNVERIFY is explicitly given, verification support is not available and this option is thus always required. (The -lcrypto linker flag can be omitted in this case.)

config

Path to the configuration file, see below for details.

For a continuous operation, imapsrt can be periodically called in batch mode by a simple script or loop, so no actual daemonization is needed.

Configuration and filters

The config file states the mail accounts to use, the matches to perform on mail properties, and the folders to process.

server server-id host port user pass

Defines a new IMAP server with some arbitrary string as identifier. As imapsrt uses direct SSL connections (i.e. not STARTTLS), the port will usually be 993. The login credentials have to be valid for the plain authentication method, which most servers should support and allow for encrypted connections. In interactive mode, an empty quoted string as password will be prompted for when needed.

match match-id …

Defines a filter expression in IMAP SEARCH syntax. Currently supported IMAP search matches are: CC, FROM, SUBJECT, TO (all taking a single string argument), HEADER (expecting a header name and a string), NOT (match prefix), and SEEN (single flag). As per convention, multiple expressions in a row have all to match (AND). In contrast, repeated match-id definitions will be OR’ed together.

server-id inbox match-id dst-folder

States an actual task to perform with the mailbox folders to search in and move to, respectively. The id parameters refer to a previously defined server or match. Each task is processed in the given order for each server.

Example configuration file e.g. checking an inbox for spam:

# define site and credentials for JohnFoo's account
server JohnFoo imap.example.com 993 JohnFoo@example.com "p4ssw0rd"
# define two matches to be used lateron
match spam SUBJECT "Buy Now!"
match spam SUBJECT pr0n NOT FROM buddy@example.com
match spam TO trashAlias@example.com
match priv FROM JaneFoo@example.com
# look into JohnFoo's inbox and move matching mails accordingly
JohnFoo Inbox priv Private
JohnFoo Inbox spam "Bulk Mail"