MAILPROCESSING(1)

📦 version 1.2.7, in fedora 43, fedora 44

💌 MAILPROCESSING(1) — the mailprocessing rc file, explained by your bestie

okay so welcome to the mailprocessing manpage, aka the docs for the config files ~/.mailprocessing/imap.rc and ~/.mailprocessing/maildir.rc — the filter configuration for mailprocessing. it's in the User Commands section of the manual, and bestie, it's giving power. 🦋

✨ SYNOPSIS ✨

processor.maildir_base = '/home/user/Maildir'
for mail in processor:
  pass

🌸 DESCRIPTION 🌸

okay so here's the tea, and it's actually the most important thing on this whole page: the rc file for maildirproc and imapproc is not a set of declarative rules. not even a little. it's literally just a simple Python program. 💅

that program gets access to a "maildir processor" object, and that object produces mail objects. your entire mail processing logic is just if/elif/else statements, and you do stuff by calling methods on the mail objects. that's it. that's the whole vibe. no cap. ✨

maildir-specific and IMAP-specific functionality is implemented by the MaildirProcessor and ImapProcessor classes, respecitively.

👑 The MailProcessor class

iterating over a MailProcessor instance yields Mail instances. imapproc and maildirproc will create a MailProcessor instance for you, and it's available as the global processor variable in the rc file's name space. so you never have to construct it yourself. slay. 🫶

🎀 Readable and writable properties

  • auto_reload_rcfile — whether the rc file should be automatically reloaded when it has been modified. assigning to this property overrides the corresponding command-line option.
  • maildir_base — the base directory of maildirs. assigning to this property overrides the corresponding command-line option. this property is specific to MaildirProcessor instances.
  • maildirs — a list of maildirs (subdirectories of the maildir base directory). assigning to this property overrides the corresponding command-line option. this property is specific to MaildirProcessor instances.
  • folders — a list of IMAP folders. assigning to this property overrides the corresponding command-line option. this property is specific to ImapProcessor instances.

🧚 Methods

  • create_folder(folder, parents=True, prefix='.') — creates folder folder (a string, or a list of namespace components). it is totally safe to call this for folders that already exist: if the folder is already there, the method logs that it exists and exits without trying to create it. for MaildirProcessor, folder does not need to be on the same file system as the mail. if the folder path is relative, it gets treated as relative to the maildir base directory. the boolean keyword argument parents decides whether parent folders get created too — like, if you create 'github.jrosdahl.maildirproc', then 'github' and 'github.jrosdahl' get created as well. that's the default behaviour, bestie. the prefix keyword argument is a prefix to prepend the folder name with; it defaults to the processor's prefix attribute, which gets set via the --prefix command line attribute for MaildirProcessor instances. 💖

🍓 Writable properties

  • logfile — location of the log file. assigning 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. example time:

for mail in processor:
  myheader = mail['From']

🌟 Readable properties

  • folder — the IMAP folder in which the mail is situated. only applicable for ImapProcessor.
  • maildir — the maildir in which the mail is situated. only applicable for MaildirProcessor.
  • path — full filesystem path to the mail. only applicable for MaildirProcessor.
  • target — a Target instance.

🦋 Methods

  • copy(maildir, create=False) — 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 gets treated as relative to the maildir base directory. if you set the optional create keyword argument to True, the folder (and its parent folders) will be created if it doesn't exist. by default, non-existent folders are not created.
  • delete() — delete the mail. bye bestie. 💀
  • 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.
  • strict_mailing_list(list) — check whether the mail originated from the mailing list list (a string). it's a bit stricter than from_mailing_list() and only matches the content of typical mailing list headers, namely List-Archive, List-Help, List-ID, List-Post, List-Subscribe and X-Mailing-List.
  • is_seen() — returns True if the message has been seen by the user, False otherwise.
  • is_flagged() — returns True if the message has been flagged by the user, False otherwise.
  • move(maildir, create=False) — 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. for MaildirProcessor, a relative maildir path gets treated as relative to the maildir base directory. if you set the optional create keyword argument to True, the folder (and its parent folders) will be created if it doesn't exist. by default, non-existent folders are not created.
🚨 not me warning you about move(): if it's not the same file system, it's a no-op plus a log line. plan accordingly, bestie.

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

🔥 EXAMPLES 🔥

for some examples, see the examples directory. go peek, it's worth it, fr fr. 👀

🫶 SEE ALSO 🫶

imapproc(1), maildirproc(1) — your other besties, go say hi. 🌸

and that's the whole page, bestie!! this one lives in the User Commands section of the manual, and this version of it is dated to match the mailprocessing page as shipped — so like, that's the source and the date, folded into this little sign-off instead of a boring footer line. mwah. 💅✨🎀🦋

📦 where this page comes from