MAILDIRPROC(1)

NAME
maildirproc - filter emails in local Maildirs

SYNOPSIS

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

DESCRIPTION
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.

OPTIONS

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

--version
    show program's version number and exit

-h, --help
    show this help message and exit

--auto-reload-rcfile
    turn on automatic reloading of the rc file when it has been modified

--dry-run
    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.

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

--once
    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
    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:

-m DIRECTORY, --maildir=DIRECTORY
    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.

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

SIGNALS
Both SIGINT and SIGTERM will cause maildirproc to shut down cleanly, i.e. it will finish processing any already-queued emails, then exit. While it is generally safe for maildirproc to be interrupted by other signals that may cause it to terminate abnormally, this clean-shutdown is still useful to avoid a non-zero exit status.

SIGHUP will cause maildirproc 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)