archmbox(1)

📦 version 4.10.0, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu questing

💖 archmbox — a simple email archiver 💖

okay bestie, pull up a chair, we're doing archmbox(1) and it's genuinely iconic. it's a simple email archiver, no cap. let's get into it.

✨ SYNOPSIS ✨

archmbox [ -h | --version ]
archmbox MODE [ OPTIONS ] -d date mailbox [ mailbox ... ]
archmbox MODE [ OPTIONS ] -o days mailbox [ mailbox ... ]

🌸 DESCRIPTION 🌸

so Archmbox is a simple email archiver, and the way it's written is perl 🧚 — it parses one or more mailboxes, selects some or all messages, and then does specific actions on the ones it picked. that's the whole vibe.

There are four different MODES available, and yes you have to pick one:

  • list mode, which is useful to list all selected messages before archmbox performs the real operations (archiving or deleting)
  • kill mode, if messages should be deleted from the mailbox(es) rather than archived
  • archive mode, to archive the selected messages in a different mailbox
  • copy mode, to copy selected messages from a source mailbox(es) without modifying it

Messages selection is based upon a date criteria; an absolute date or a days offset can be specified. pick your fighter.

It is also possible to refine the selection using perl regular expressions on the header fields of the message. Keep in mind to quote the so called metacharacters, which are reserved for use in perl's regex notation. The metacharacters are

{}[]()^$.|*+?\
⚠️ bestie. QUOTE THEM. the regex will eat your shell alive otherwise. 😭

All archived messages are stored in a new mailbox with the same name of the original one + .archived as extension (this is the default, but can be changed); the archive mailbox can be saved in gz or bz2 compressed format as well. slay.

Please note that the archive mailbox format is always mbox, regardless of original mailbox format. Moreover, mailboxes must be specified using the full path. like, the whole thing. no shortcuts.

Messages are appended to the archive mailbox to allow multiple executions of the script against the same mailbox. it just keeps adding, it's giving loyal 🫶

👑 MODES 👑

  • -a, --archive — Selected messages are archived in a different mailbox.
  • -k, --kill — Selected messages are deleted rather than archived. 💀
  • -l, --list — List all selected messages. Warnings about skipped mailboxes (in use, empty ...) are printed to stderr. So redirecting them to /dev/null won't clutter your list. iykyk
  • -y, --copy — Selected messages are copied from the source mailbox.

💅 OPTIONS 💅

  • -b, --backup — Creates a backup of the original mailbox before archmbox execution. The mailbox is called mailbox.backup. be safe bestie 🎀
  • --bzip2 — Use bzip2 to compress the archive mailbox (use with -c).
  • -c, --compress — Compress the archive mailbox after script execution.
  • *-d, --date *<date> — Specifies the threshold date for messages. The date must be supplied in the following format: yyyy-mm-dd
  • -D, --date-header — Force the use of the "Date:" header to age a message. If the header is somehow corrupt, the date/time information are gathered for the beginning line of the message.
  • *-e, --extension *<extension> — Specifies the suffix for the archive mailbox; the default is archived. If none is specified, no suffix will be used (use carefully). 👀
  • -f, --full-name — Prepends the path of the mailbox to the name of the archive mailbox. This option overrides -n.
  • --format — Specifies the format of the mailboxes to parse. Legal values are mbox and mbx. Defaults to "mbox".
  • -h, --help — Prints help.
  • *-i, --ignore *<regexp> — Any mailbox/directory matching <regexp> will be skipped while archiving.
  • --keep-flagged — Flagged messages will not be archived.
  • --keep-unread — Unread messages will not be archived.
  • -m, --minsize — Specifies the minimum size of the mailbox to be archived. Mailboxes smaller than <minsize> will not be parsed for archiving.
  • -n, --archive-name — Specifies the name of the archive file (default: mailbox name)
  • --nosymlink — Do not follow symbolic links when processing mailboxes.
  • --nowarnings — Suppress mailbox related warnings. Use only if you know what you're doing!
  • *--omit-prefix *<prefix> — Omit <prefix> from the name of the mailbox when full name (option -f) is required.
  • *-o, --offset *<days> — Specifies the offset (in days) from today for threshold date of a message. This option replaces -d. If you specify -1, archmbox will operate on all messages. all of them. every single one.
  • *-p, --archive-path, --path *<directory> — Specifies where to store the archive mailbox (default: "."). <directory> must be specified using full path. The --path option is now deprecated and will be dropped in future releases.
  • -r, --reverse — Reverse the sense of offset or date value. It usually means older than but with this switch, it means newer than. plot twist 🦋
  • -R, --recursive — Act recursively on directories. If one or more directories are specified on the command line, all mailboxes stored in those directories will be parsed for archiving. Implies option -f.
  • *-t, --tmpdir *<directory> — Specify a temporary working directory. This value overrides the default one, which will be set in descending order to the first defined one of: the environment variables $TMPDIR and $TMP, the compiled in one and, as a fallback, '/tmp'. To see the default value used by archmbox, do: archmbox --help. <directory> must be specified using full path.
  • *--time *<time> — Use <time> in conjunction with <date> (option -d) to refine the threshold age for archiving. <time> must be specified in the following format: hh:mm:ss.
  • --totals — Prints an overall summary of the archiving operations. The summary contains the number of parsed and skipped mailboxes, the total number of messages parsed and saved, the total space used and saved. receipts, bestie. 🧾
  • -v, --verbose — Verbosity level. Default is 1 (line per message) in --list output. So, if set to 1 it only lists msgid, sender and subject. With -v=2, it also prints date.
  • --version — Prints version number.
  • *-x, --regexp *<header=regexp> — It is specified in form -x field='regexp', where field can be any header. The header part is case sensitive. The regexp part is case sensitive if the regexp contains at least one upper case letter, and case insensitive otherwise. If message satisfies date range, but does not satisfy regexp match on specified field, it won't be archived. The option can be specified more than once; in this case, the message is regexp matched against all the given rules, and if it satisfies any, it will be archived.
  • *-X, --Regexp *<header=regexp> — Same as -x, --regexp except that for matching the regular expressions a logical 'and' mode is used for all regexp including the regexp given by -x, --regexp.

🎀 CONFIGURATION 🎀

Archmbox is completely written in perl, but it uses some shell helpers to perform its job (fuser, rm, gzip/gunzip etc.). tiny little guys doing the work behind the scenes, love that for them.

The correct path for the helpers (both required and optional ones) is probed at installation time. If one required helper is missing the installation will not take place. If one optional helper is missing, the feature provided using that helper will be unavailable, but the script will be installed anyway. so like, optional friends are optional, required friends are required. periodt.

All other relevant configuration options can be specified at installation time or at run time using the command line switches. ✨

✨ USAGE EXAMPLES ✨

Okay bestie, this is the part where it all clicks. Starting with the full deluxe example:

archmbox -a -b -c -e 01 -f -d 2002-01-01 -p ~/mail-archive
~/Mail/personal-stuff

What this does: it archives every message older than (aka received before…) Jan 1st 2002 from the personal-stuff mailbox inside the Mail directory. The archived messages get saved into a mailbox called Mail-personal-stuff.01.gz in the ~/mail-archive directory. And after it runs, you'll find a mailbox named personal-stuff.backup chillin' in ~/Mail. 💅

Now for the complex examples, and yes they use perl regular expressions, so buckle up:

archmbox -a -o 1 --keep-flagged --keep-unread \
   -x From='(nagios|arpwatch|logcheck)@host\.net' \
   -x Subject='^(Security Events|Syslog Summary|\[SNORT\])' \
   ~/Mail/inbox

Translation: this archives all unflagged, read messages older than 1 day where the sender address matches nagios@host.net, arpwatch@host.net or logcheck@host.net — or where the subject field starts with either 'Security Events', 'Syslog Summary' or '[SNORT]' — out of the mailbox ~/Mail/inbox. The messages get saved in inbox.archive in the current directory, aka wherever you started archmbox from. 🫶

archmbox --archive --offset 1 --keep-flagged --keep-unread \
   --Regexp From='@(host1|host2).example\.com' \
   --regexp Subject='^(Security Events|Syslog Summary|\[SNORT\])' \
   --archive-path ~/Mail/local-network.archive \
   --archive-name system-msgs \
   --extension 'none' \
   ~/Mail/inbox

Same energy, long-option edition: archives all unflagged, read messages older than 1 day where the sender address matches @host1.example.com or @host2.example.com and the subject field starts with either 'Security Events', 'Syslog Summary' or '[SNORT]', from the mailbox ~/Mail/inbox. The messages get archived to the mbox system-msgs in the directory ~/Mail/local-network.archive. 📬

And now, the snack-sized ones:

archmbox -a -o 15 ~/Mail/personal-stuff

Archives all messages older than 15 days into personal-stuff.archived (an uncompressed mailbox, no cap).

archmbox -a -r -o 15 ~/Mail/personal-stuff

Same as above, except it flips it — only messages newer than 15 days get archived.

archmbox -k -o 15 ~/Mail/personal-stuff

This one deletes all messages older than 15 days from Mail/personal-stuff. Yes, deletes. Be so careful. 😭

archmbox -a -o 15 ~/Mail/* -c

Archives all messages older than 15 days in every mailbox found in ~/Mail. All the archive mailboxes come out compressed. ✨

archmbox -l -r -c /tmp/mbox -o 20

Lists all messages in /tmp/mbox that are newer than 20 days. And option -c? It's meaningless here, so it just gets ignored. Bye. 👋

archmbox -l -r -c /tmp/mbox -o 20 -a --bzip2

Same as above, but now archiving is forced (-a) and bzip2 handles the compression.

archmbox -a -x Subject='archmbox' -o 7 ~/mbox

Selects for archiving all messages older than 7 days whose subject field satisfies the regexp match Subject =~ /archmbox/ — and heads up, Subject is case sensitive while archmbox is case insensitive.

archmbox -l -x Subject='archmbox' -x From='fritz' -o 7 ~/mbox

Selects for archiving all messages older than 7 days whose subject field contains archmbox or whose sender is fritz (matches are case insensitive).

archmbox -l -x Subject='archmbox' -X From='fritz' -o 7 ~/mbox

Selects for archiving all messages older than 7 days whose subject field contains archmbox and whose sender is fritz (matches are case insensitive). Sneaky little -x vs -X difference, iykyk. 💅

archmbox -a -o 5 -R /tmp/mbox ~/Mail

archmbox will archive all messages older than five days in /tmp/mbox. Then it starts parsing all mailboxes stored in ~/Mail (recursion is active, and ~/Mail is a directory). If one or more directories get found in ~/Mail, those directories get explored as well. Down the rabbit hole we go. 🐇

archmbox -a -o -1 ~/Mail/my_mbx_mailbox --format mbx

archmbox archives all messages stored in my_mbx_mailbox and puts them into my_mbx_mailbox.archived. The source mailbox is a mbx mailbox (that's what --format mbx is doing there). The archive mailbox will be a mbox mailbox.

🧠 NOTES 🧠

So when the script has to decide if a message needs to be selected from the mailbox, it looks for the From header generated by the mail server (that's the first line of the message) and it does not care about the date specified by the sender's mail client. This is genuinely useful — it saves you from removing messages sent by misconfigured mail clients. You can change this behavior by forcing the use of the "Date:" header (option -D).

Not all options are meaningful in all modes, like compression is meaningless in list or kill mode. If you specify a useless option for a particular mode, archmbox simply ignores it. No drama. 💅

Archmbox uses a working directory to store temporary mailboxes. A default value for that directory is hard coded in the script, but it can be changed during the configuration/installation process (see INSTALL for details). Here's the thing though — it might happen that your mailboxes are too big for the partition holding this temporary directory, or you might want to perform archiving on too many mailboxes at the same time. In other words: you may run out of space. Use the -t option to specify a suitable working directory at runtime.

If you see some differences in the mailbox's dimension (size/free space), keep in mind that your mailbox may contain a special message (512 bytes in size) with internal information related to the mailbox. This message is meaningless for you, though archmbox recognizes it and lets you be aware of it. That message is left untouched in your source mailbox. 🫶

A few words about locking. There has been a discussion about how archmbox handles file locking. The answer is simple: no mailbox is ever locked. The reason behind this behavior is that the author wants archmbox to be as least invasive as possible, so other kinds of checks are performed to ensure that no data is lost (mailbox has changed / mailbox is in use by another program). Some locking mechanism will surely be added in the future.

You don't need to execute archmbox as root… just take care to have write permissions for the directories you use. 👑

Archmbox can be downloaded from:

http://adc-archmbox.sourceforge.net

Archmbox is distributed under the terms of the GPL.

👑 AUTHOR(S) 👑

Copyright (C) 2001-2005

Alessandro Dotti Contra <adotti@users.sourceforge.net>

Parts of the code were contributed by:

Alex Aminoff, Brian Medley, Buck Holsinger, Davor Ocelic, Fabrice Noilhan, Jayanth Varma, Juergen Edner, Laurent Cheylus, Nicolas Ecarnot, Paco Regodon, Scott Thompson, Juergen Desher.

The FreeBSD port is maintained by Talal Al-Dik. The OpenDarwin port is maintained by Markus Weissman. The Debian package is maintained by Alberto Furia <straluna@email.it>

🐛 BUGS 🐛

Please report bugs to <adotti@users.sourceforge.net>. (Be nice, they're doing their best. 💖)

👀 SEE ALSO 👀

PERLREQUICK(1), PERLRETUT(1), PERLRE(1)

And that's a wrap bestie!! 🎀 This whole thing is the archmbox(1) manual page — that's the footer, periodt. Go archive something responsibly, protect your mailboxes, and remember: no mailbox is ever locked. 💅✨🦋

📦 where this page comes from