maildirproc - Man Page

filter emails in local Maildirs


maildirproc -m <maildir> [-m <maildir> ... ] [options]


maildirproc continuously monitors one or more maildirs and processes mail in them according to logic in an rc file, a user defined piece of Python code. It also logs its actions to a log file. By default maildirproc operates continuously: when there is no more mail to process, maildirproc sleeps one second and then checks again. And so on. To make maildirproc exit after the first filtering run, pass the --once option.

maildirproc keeps a list of maildir directories to process. At least one maildir directory must be specified for maildirproc to run. A maildir directory path can be absolute (starting with a slash) or non-absolute. In the latter case, it will be considered relative to the maildir base directory, which defaults to the current working directory. There are two ways to specify this information: by passing command line options, or by setting attributes on the processor object in the rc file. The rc file has priority over the command line options.

In a Maildir++-style setup, the maildir base directory should typically be set to ~/Maildir and the maildir list should include the directory . to make maildirproc process the inbox.

The default location of the rc file for maildirproc is ~/.mailprocessing/maildir.rc and the default location of its log file is ~/.mailprocessing/log-maildir.

imapproc can optionally reload the rc file whenever a modification is detected (that is, the file's mtime has changed). This automatic reloading is turned off by default and can be enabled either by passing the --auto-reload-rcfile command line option or by setting the auto_reload_rcfile property to True on the processor object in the rc file.


Common options

maildirproc and imapproc both take the following common command line options:


show program's version number and exit

-h, ā€‰--help

show this help message and exit


turn on automatic reloading of the rc file when it has been modified


just log what should have been done; implies --once

-l FILE, --logfile=FILE

send log to FILE instead of the default (~/.maildirproc/log-imap for imapproc and ~/.maildirproc/log-maildir for maildirproc). If you are running multiple maildirproc or imapproc instances, you must specify a dedicated log file for each of these.


only include log messages with this log level or lower; defaults to 1


only process the maildirs once and then exit; without this flag, maildirproc will scan the maildirs continuously

-r FILE, --rcfile=FILE

use the given rc file instead of the default (~/.maildirproc/default.rc)


test mode; implies --dry-run, --once, --logfile=- and --verbose

-v, ā€‰--verbose

increase log level one step

maildirproc specific options

The following options are specific to maildirproc:


add DIRECTORY to the set of maildir directories to process (can be passed multiple times); if DIRECTORY is relative, it will be considered relative to the maildir base directory

-b DIRECTORY, --maildir-base=DIRECTORY

set maildir base directory; defaults to the current working directory

-p PREFIX, --folder-prefix

prefix Maildir names with PREFIX; defaults to '.'

-s SEP, --folder-separator=SEP

use sep as a folder separator in maildir names; defaults to '.'. List style folder names passed to create_folder() will be joined by this character, e.g. ["github", "jrosdahl", "maildirproc"] will become ".github.jrosdahl.maildirproc.


For some mailprocessing configuration examples, see the examples directory. You will also find sample logrotate configuration files for mailprocessing in there.


SIGHUP will cause imapproc to close and re-open its log file. This can be used for online log rotation in continuous mode.

See Also

imapproc(1), mailprocessing(5)

Referenced By

imapproc(1), mailprocessing(5).