maildirproc reference
Examples
For some examples, see the examples directory.
Default behaviour
By default, maildirproc continuously monitors a number of maildirs and processes
mail in them according to logic in an rc file. It also logs its
actions to a log file. When there is no more mail to process,
maildirproc sleeps one second and then checks again. And so on. To
make maildirproc exit when there is no mail left, 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 is ~/.maildirproc/default.rc and the default
location of the log file is ~/.maildirproc/log.
maildirproc 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.
Command line options
maildirproc takes these 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)
- --log-level=INTEGER
- only include log messages with this log level or lower; defaults to 1
- -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
- --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
Configuration
maildirproc's configuration, the rc file, is not a set of
declarative rules. Instead, it is a simple Python program that has access to a
"maildir processor" object which produces mail objects. The mail
processing logic is defined in terms of if/elif/else statements and
actions are performed by calling methods on the mail objects.
The program has access to one special object: the processor object, which is an instance of
the MaildirProcessor class.
The MaildirProcessor class
Iteration over a MaildirProcessor
instance yields Mail
instances.
Readable and writable properties
- auto_reload_rcfile
- Whether the rc file should be automatically reloaded when it has been modified. Assignment to this property overrides the corresponding command-line option.
- maildir_base
- The base directory of maildirs. Assignment to this property overrides the corresponding command-line option.
- maildirs
- A list of maildirs (subdirectories of the maildir base directory). Assignment to this property overrides the corresponding command-line option.
Writable properties
- logfile
- Location of the log file. Assignment to this property overrides the corresponding command-line option.
The Mail class
Indexing a Mail instance with
a header name (a string) returns a Header instance.
Readable properties
- maildir
- The maildir in which the mail is situated.
- path
- Full filesystem path to the mail.
- target
- A Target instance.
Methods
- copy(maildir)
- Copy the mail to maildir (a string). maildir does
not need to be on the same file system as the mail. If the
maildir path is relative, it will be considered relative to the
maildir base directory.
- delete()
- Delete the mail.
- forward(addresses[, env_sender])
- Forward the mail to one or several e-mail addresses and delete the
mail. addresses can be either a string or a list of
strings. env_sender (optional) specifies which envelope sender address
to use.
- forward_copy(addresses[, env_sender])
- Forward a copy of the mail to one or several e-mail
addresses. addresses can be either a string or a list of
strings. env_sender (optional) specifies which envelope sender address
to use.
- from_mailing_list(list)
- Check whether the mail originated from the mailing list
list (a string). Currently, the headers Delivered-To,
Mailing-List, X-BeenThere and X-Mailing-List are checked. Returns a
boolean.
- move(maildir)
- Move the mail to maildir (a
string). maildir must be on the same file system as the
mail, otherwise nothing will happen and an error will be logged. If
the maildir path is relative, it will be considered relative to
the maildir base directory.
The Header class
Methods
- contains(case-insensitive-string)
- Check whether case-insensitive-string is part of the header. Returns a boolean.
- matches(case-insensitive-regexp)
- Check whether case-insensitive-regexp (with an
implicit .* prefix) matches the header.
Returns a boolean.
The Target class
Methods
- contains(case-insensitive-string)
- Check whether case-insensitive-string is part of the To or Cc header. Returns a boolean.
- matches(case-insensitive-regexp)
- Check whether case-insensitive-regexp (with an
implicit .* prefix) matches the To or Cc
header. Returns a boolean.