IMAPPROC(1)

📦 version 1.2.7, in fedora 43, fedora 44

🌸 NAME 🌸

okay bestie, welcome to imapproc — she's in the User Commands section of the manual, she's manual page IMAPPROC(1), and her whole job is: filter emails in remote IMAP folders 💌✨

🎀 SYNOPSIS 🎀

imapproc -H <host> -u <user> --password <password>    [options]
imapproc -H <host> -u <user> --password-command <cmd> [options]

🦋 DESCRIPTION 🦋

So here's the vibe: imapproc is out here continuously monitoring one or more remote IMAP folders, and processing the mail inside them according to user defined Python code in an rc file — yes, an rc file that is literally a user defined piece of Python code. 👑 She also logs everything she does to a log file, because receipts matter. When there's no more mail to process, imaproc (yes, that's how the page spells it right there, we don't question the typo, we love her) sleeps for one second and then checks again. And so on. Forever. If you want her to bounce after the first filtering run instead of vibing eternally, pass the --once option. 💅

imapproc keeps a list of folders in the IMAP account to process. At least one IMAP folder must be specified for imapproc to run — that's not optional, bestie, she needs somewhere to be. Folder paths are always absolute. There are two ways to feed her this info:

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

And plot twist — the rc file has priority over the command line options. 🙈

The typical folder to run imapproc on is INBOX, but obviously you can specify multiple folders to process. She contains multitudes. 🌈

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

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 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. Pick your fighter. ⭐

imapproc writes its process ID to ~/.mailprocessing/imapproc.pid and uses that PID file for locking as well. If you want to run multiple imapproc instances in parallel, use the --pidfile and --logfile options to give each process a different PID and log file. Sharing is not caring here. 💀

✨ 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. no sharing, bestie 🫶
  • --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

🌸 imapproc specific options

  • -C, --cache-headers — Whether to cache the email headers retrieved from the IMAP server. By default caching is disabled.
  • --cache-file FILE — Store the email header cache in FILE if caching is enabled. If this is not specified explicitly, ~/.maildirproc/HOST.cache will be used, where HOST is the IMAP server's host name passed set with the --host option.
  • -c CERT, --certfile — Use SSL certificate file CERT to verify IMAP server's SSL certificate (only relevant for IMAPS)
  • -H HOST, --host — Connect to IMAP server HOST. This option is mandatory 🚨
  • -i INTERVAL, --interval — Scan IMAP folders for new email every INTERVAL seconds; defaults to 300; will be ignored if --once is specified as well
  • --flag-batchsize SIZE — Batch size to use when fetching message flags. Defaults to 200. When there are more messages to fetch flags for, multiple FETCH commands will be issued, each with SIZE or fewer messages. Reduce this value if you experience session expiry during message flag retrieval.
  • --header-batchsize SIZE — Batch size to use when fetching message headers. Defaults to 200. When there are more messages to fetch headers for, multiple FETCH commands will be issued, each with SIZE or fewer messages. Reduce this value if you experience session expiry during message header retrieval.
  • --folder-prefix PREFIX — Prefix folder names with the string PREFIX. This is relevant for some IMAP servers that store all folders as subfolders of INBOX. imapproc will attempt to detect this situation, but this detection may not work with all server side IMAP implementations. If this is the case for your IMAP server, use this option to specify a prefix explicitly.
  • --folder-separator SEP — Use SEP as a separator for folder hierarchies. By default, imapproc will determine the folder separator from the server's LIST response. This should work fine for most IMAP servers.
  • -p PW, --interval — Use password PW to authenticate against IMAP server; since this will show up in the process list, this is mainly intended for debugging. Use --password-command otherwise. Either this option or --password-command is mandatory.
  • --pidfile FILE — Write the imapproc process' PID to FILE rather than the default location ~/.imapproc/imapproc.pid. This file is also used for locking so if you need to run multiple different imapproc processes in parallel you need to specify different PID and log files for these.
  • --password-command CMD — Run command CMD and send use its output as the password to authenticate against the IMAP server with. This is the recommended approach for specifying the IMAP password. Either this option or --password is mandatory.
  • -P PORT, --port — IMAP port to use. Defaults to 143 if --use-ssl is not specified and 993 if it is.
  • -s, --use-ssl — Use SSL to connect to the IMAP server (default: no).
  • -U USER, --user — Log in to the IMAP server with user name USER. This option is mandatory 🚨
  • --insecure — Do no certificate validation when connecting to an SSL IMAP server (default: no). This means the certificate subject names will be ignored, as will any certificate authorities. Your connection will not be protected from active attackers.
⚠️ okay real talk bestie: --insecure is not a cute little aesthetic choice. Certificate validation is the whole point. Do not do this unless you know exactly what you're doing. 🚩

🍓 EXAMPLES 🍓

For some examples, see the examples directory.

🌟 SIGNALS 🌟

Both SIGINT and SIGTERM will cause imapproc to shut down cleanly, i.e. it will close the IMAP connection and write the current in-memory cache to disk upon receiving either of these signals. She's dramatic but she's tidy. 💅

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 👑

and that's the whole page, bestie 🫶 she lives in the User Commands section of the manual, filed under IMAPPROC(1) — go forth and filter those emails, you absolute icon 💖✨

📦 where this page comes from