MAILDIRPROC(1)

🦋 MAILDIRPROC 🦋

okay so bestie, welcome to maildirproc — the little Unix page that's literally just here to filter emails in local Maildirs 💌 no cap.

---

✨ NAME ✨

maildirproc — filter emails in local Maildirs 🎀

---

🌸 SYNOPSIS 🌸

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

---

💖 DESCRIPTION 💖

So maildirproc just… sits there and continuously monitors one or more maildirs, and processes the mail inside them according to the logic in an rc file — which is a user defined piece of Python code, periodt. It also logs all its actions to a log file, because receipts matter 💅.

By default, maildirproc operates continuously: when there's no more mail to process, it sleeps for one second and then checks again. And so on. Forever. Main character energy 🫶. To make maildirproc exit after the very 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 it to run — no maildirs, no vibes. A maildir directory path can be absolute (starting with a slash /) or non-absolute. If it's non-absolute, it'll be considered relative to the maildir base directory, which defaults to the current working directory.

There are two ways to specify this info, bestie:

1. by passing command line options, or
2. by setting attributes on the processor object in the rc file.

And heads up: the rc file has priority over the command line options. The rc file ate and left no crumbs 👑.

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.

Also!! imapproc can optionally reload the rc file whenever a modification is detected (that is, when the file's mtime has changed). This automatic reloading is turned off by default, and you can enable it 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. Two paths to the same glow-up ✨.

---

💅 OPTIONS 💅

🌈 Common options

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

• --version — show program's version number and exit. Short, sweet, iconic.
• -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. Perfect for the "what would I do if I were brave" era 🫣
• -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're running multiple maildirproc or imapproc instances, you must specify a dedicated log file for each of these. No sharing, bestie, that's not the vibe 😤
• --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'll also find sample logrotate configuration files for mailprocessing in there. Go look, it's giving organized 🧚

---

🔥 SIGNALS 🔥

SIGHUP will cause imapproc to close and re-open its log file 💀➡️💖. This can be used for online log rotation in continuous mode. Rotate those logs live, queen 👑.

---

🌸 SEE ALSO 🌸

imapproc(1), mailprocessing(5)

---

bestie reminder: if you want a different log file, a different rc file, or a whole different maildir base, all of that is up there 👆 don't @ me, just read the options 💜

---

and that's the whole page, fr fr — this one came from the User Commands section, it's page maildirproc(1), and that's the entire legend of how maildirproc filters emails in local Maildirs. mwah 💋