IMAP mailbox filter

IMAP mailbox filter tool that remotely sorts emails into folders according to matching rules. Manages multiple accounts without requiring additional software.

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 is a Python-based reimplementation of the initial and now legacy C++ IMAP sort project with a more from-scratch objective.

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

At least those were the use-cases 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.

Usage and installation

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

usage: imapsrt.py [-h] [--verbose] [--dry-run] [--force]
                  [--config CONFIG.INI] [--limit-account NAME] [--limit-match NAME]

Server-side search and move for IMAP mailboxes.

options:
  -h, --help            show this help message and exit
  --verbose             enable debug logging (default: False)
  --dry-run             only search, do not actually move (read-only mode) (default: False)
  --force               skip feature detection checks for needed capabilities (default: False)
  --config CONFIG.INI   path to configuration file (default: ./imapsrt.ini)
  --limit-account NAME  only process matches for the given account name (default: None)
  --limit-match NAME    only process matches with the given name (default: None)

Apart from a standard Python 3 environment, no dependencies are required. Installation is thus not needed, and the script can be executed directly. However, for convenience, make install can be used to create /usr/local/bin/imapsrt.

Configuration file

The configuration file is assumed to be in Python’s INI file format. Most importantly, account and match sections (with their unique name after the first dot) can be given in [] brackets, line comments with ; or #, and lists are suppported by (indented) multiline values.

For example, the following will move certain emails from the Inbox folder to Bulk on a Yahoo account:

[account.yahoo-foo]
host = imap.mail.yahoo.com
port = 993
user = foo@yahoo.com
; utf = true
; password = sup3rs3cr3t

[match.yahoo-spam1]
account = yahoo-foo
from_mailbox = Inbox
to_mailbox = Bulk
match_any = true
match =
    FROM @secretdeals.de
    FROM noreply@news.example.com
    SUBJECT V1agra

Running with this configuration will produce an output like this:

Password for 'foo@yahoo.com' on yahoo-foo: *************
[INFO] main: Checking yahoo-spam1 on yahoo-foo
[INFO] Imap: Found 42 mails in 'Inbox' for 'Bulk'

An [account.NAME] section accepts the following settings:

host
IMAP server hostname to connect to
port
IMAP server port to connect to, typically 993
user
Login username, usually the email address
password
Login password, will be prompted for at startup when omitted
utf
Enable extended UTF-8 support

Please note that the login credentials have to be valid for the plain authentication method, which most servers should support and allow for encrypted connections. If that’s not the case, a so-called app password might be supported by the mail provider as fallback mechanism, and can be used just like in any generic mail client software.

Actual matches to perform can be defined by [match.NAME] sections:

account
The name of the account this match refers to (via its section header)
from_mailbox
Folder or list of folders to search in
to_mailbox
Where to move matched emails to
match_any
Per default, all given matches have to succeed (AND); if enabled, any match suffices (OR)
match
List of matches, a single one or one per line, see below for the list of supported search filters

IMAP search filters

Matches are more or less passed through unchanged to the remote server, using the IMAP search command. Depending on match_any, they are treated as single criterion (false: and) or as independent ones (true: or). No quoting or escaping in the configuration file is needed/allowed, tokens are concatenated with a single space character. The following matches are recognized:

CC|FROM|TO <address>
Search for email addresses (or parts thereof) in the respective field
SUBJECT|TEXT <string>
Match the subject field or whole header/body for string occurrences
SEEN|UNSEEN
Select only seen or unseen messages, respectively
HEADER <header> [<value>]
Arbitrary header lookup (IMAPv4 only), for example HEADER Reply-To foo@bar.net
BEFORE|SINCE|SENTBEFORE|SENTSINCE <X> days ago
Allows restriction by time, for example SINCE 7 days ago

Code & Download