imaparms

A handy Swiss-army-knife-like utility for fetching, flagging/marking, deleting/expiring, and performing other batch operations on messages residing on IMAP servers

git clone https://github.com/Own-Data-Privateer/imaparms
git clone https://oxij.org/software/imaparms

Recent changes

Files

Raw Source

What is imaparms?

imaparms is a handy Swiss-army-knife-like tool/utility/console app for POSIX-compatible systems that can help you to download/fetch/backup all your mail/email from an IMAP server (e.g. GMail, Yahoo, Hotmail, Yandex, etc, or your own private mail server) to your hard disk, programmatically change flags on messages on the IMAP server (e.g. mark all messages newer than a day old in some folder as unread), delete/expire old messages from the IMAP server, and similar.

Or, more formally: imaparms is a utility for fetching and performing batch operations on messages residing on IMAP servers. That is: login to a specified server, fetch or perform specified actions (count, flag/mark, delete, etc) on all messages matching specified criteria in all specified folders, logout.

Or, in comparison to other things, imaparms is an advanced but fairly KISS (Keep It Stupid Simple) replacement for a combination of fetchmail/getmail and IMAPExpire, with additional features, and written in pure Python. Also, it fetches mail >150 times faster and (when using --maildir option) generates ~150 times less disk writes than fetchmail and getmail by default, and it is designed to do its very best at not losing any of your mail regardless of network connections failing unexpectedly, your IMAP server generating errors at unexpected times, other simultaneous IMAP clients making incompatible changes that could lead to future data loss, your disk failing while imaparms tries to fsync your data, and you calling imaparms with wrong command line arguments.

Screenshot

Click the above image to see the full terminal recording video of imaparms invocation (with account data edited out and replaced by fake GMail accounts in post-processing) running new-mail-hook indexing new mail with notmuch (see workflow example below), followed by a full-text search in Emacs UI of notmuch.

It was recorded on a 2013-era laptop (Thinkpad X230 with Intel Core i5-3230M CPU @ 2.60GHz upgraded with 16GB RAM and Samsung 870 EVO SSD), my notmuch database contains ~4 millions messages, and the whole search takes only 0.25 seconds in person (but about 2 seconds in the video because rendering an asciinema file to gif and then compressing it into webm adds extra time between frames, so it looks much more laggy than it actually is at the end there).

Why does imaparms exist?

If all your email experience can be summarized as “I do all my mail in GMail or similar” or if you don’t know what a Maildir is, you should start with this section below to learn why you might want to do the following.

If you

… effectively, you are using IMAP as a mail delivery protocol, not like a mail access protocol it was designed to be.

In which case you might ask yourself, wouldn’t it be nice if there was a tool that could help you automate fetching of new messages and deletion of already backed up old messages from IMAP servers in such a way that any of your own systems crashing or losing hard drives at any point in time would not lose any of your mail?

imaparms is a replacement for fetchmail/getmail that does this (and more, but mainly this).

Why would you make a replacement for fetchmail/getmail?

imaparms was inspired by fetchmail and IMAPExpire and is basically a safe generalized combination of the two.

I used to use and (usually privately, but sometimes not) patch both fetchmail and IMAPExpire for years before getting tired of it and deciding it would be simpler to just write my own thingy instead of trying to make fetchmail fetch mail at decent speeds and fix all the issues making it unsafe and inconvenient to run IMAPExpire immediately after fetchmail finishes fetching mail. The main problem is that fetchmail fetches yet-unfetched mail, while IMAPExpire expires old mail. When fetchmail gets stuck or crashes it is entirely possible for IMAPExpire to delete some old yet-unfetched messages. (And getmail suffers from exactly the same problems.)

In short, imaparms is designed to be used as a IMAP-server-to-local-Maildir Mail Delivery Agent (MDA) that makes the IMAP server in question store as little mail as possible while preventing data loss.

Which is to say, the main use case I made this for is as follows:

Also, imaparms seems to be one of the fastest, if not the fastest, IMAP fetchers there is. By default, it fetches mail >150 times faster than fetchmail (and getmail), but if your IMAP server supports long enough command lines, your system can do SSL and your hard drive can flush data fast enough, then you can saturate a gigabit Ethernet link with imaparms.

Since bootstrapping into a setup similar to the one described above requires querying into actual IMAP folder names and mass changes to flags on IMAP server-side, imaparms provides subcommands for that too.

See the “subcommands” subsection of the usage section for the list available of subcommands and explanations of what they do.

Quickstart

Installation

How to: backup all your mail from GMail, Yahoo, Hotmail, Yandex, etc

imaparms is not intended as an IMAP mirroring tool, it is intended to be used as a Mail Delivery Agent with automatic expiration of old server-side mail, i.e. a better replacement for fetchmail+IMAPExpire combination. If you want to keep a synchronized copy of your mail locally and on your mail server without sacrificing any flags, you should use offlineimap, imapsync, or something similar instead.

However, imaparms can be used for efficient incremental backups of IMAP server data if you are willing to sacrifice either of SEEN or FLAGGED (“starred”) IMAP flags for it. Also, making email backups with imaparms is pretty simple, useful, and illustrative, so a couple of examples follow.

How to: fetch all your emails from GMail, Yahoo, Hotmail, Yandex, etc

The following will fetch all messages from all the folders on the server (without changing message flags on the server side) and just put them all into ~/Mail/backup Maildir (creating it if it does not exists).

# backup all your mail from GMail
imaparms fetch --host imap.gmail.com --user account@gmail.com --pass-pinentry \
  --maildir ~/Mail/backup --all-folders --any-seen

For GMail you will have to create and use application-specific password, which requires enabling 2FA, see below for more info.

Also, if you have a lot of mail, this will be very inefficient, as it will try to re-download everything again if it ever gets interrupted.

How to: efficiently incrementally backup all your mail from GMail, Yahoo, Hotmail, Yandex, etc

To make the above efficient you have to sacrifice either SEEN or FLAGGED IMAP flags to allow imaparms to track which messages are yet to be fetched, i.e. either:

# mark all messages as UNSEEN
imaparms mark --host imap.gmail.com --user account@gmail.com --pass-pinentry \
  --folder "[Gmail]/All Mail" unseen

# fetch UNSEEN and mark as SEEN as you go
# this can be interrrupted and restarted and it will continue from where it left off
imaparms fetch --host imap.gmail.com --user account@gmail.com --pass-pinentry \
  --maildir ~/Mail/backup --folder "[Gmail]/All Mail" --unseen

or

# mark all messages as UNFLAGGED
imaparms mark --host imap.gmail.com --user account@gmail.com --pass-pinentry \
  --folder "[Gmail]/All Mail" unflagged

# similarly
imaparms fetch --host imap.gmail.com --user account@gmail.com --pass-pinentry \
  --maildir ~/Mail/backup --folder "[Gmail]/All Mail" --any-seen --unflagged

This, of course, means that if you open or “mark as read” a message in GMail’s web-mail UI while using --unseen, or mark it as flagged (“star”) it there while using --unflagged, imaparms will ignore the message on the next fetch.

How to: efficiently incrementally backup millions and/or decades of messages from GMail, Yahoo, Hotmail, Yandex, etc

In cases where you want to fetch millions of messages spanning decades, you’ll probably want invoke imaparms fetch multiple times with progressively smaller --older-than arguments so that IMAP SEARCH command responses will be smaller to re-fetch if the process gets interrupted, i.e.:

# mark all messages as UNSEEN
imaparms mark --host imap.gmail.com --user account@gmail.com --pass-pinentry \
  --folder "[Gmail]/All Mail" unseen

for n in 10 5 3 2 1; do
    echo "fetching mail older than $n years..."
    imaparms fetch --host imap.gmail.com --user account@gmail.com --pass-pinentry \
      --maildir ~/Mail/backup --folder "[Gmail]/All Mail" --unseen \
      --older-than $((365*n))
done

What do I do with the resulting Maildir?

You feed it into sup, notmuch, or similar, as discussed this section, and it gives you a GMail-like UI with full-text search and tagging, but with faster search, with no cloud storage involvement, and it works while you are offline.

Or you just repeat this mirroring on a schedule so that when/if GMail decides to take your mail hostage you will be prepared to switch.

Can I use an MDA/LDA to deliver messages?

Yes, just replace --maildir DIRECTORY with --mda MDA. For instance, for maildrop Mail Delivery Agent (also knows as Local Delivery Agent, LDA, as it is an MDA that gets used to deliver messages to same machine) from Courier Mail Server project — which is a commodity MDA/LDA with the simplest setup, that I know of — the simplest imaparms fetch invocation looks like this:

### setup: do once
mkdir -p ~/Mail/backup/{new,cur,tmp}

cat > ~/.mailfilter << EOF
DEFAULT="\$HOME/Mail/backup"
EOF

# backup all your mail from GMail
imaparms fetch --host imap.gmail.com --user account@gmail.com --pass-pinentry \
  --mda maildrop --all-folders --any-seen

Of course, you can use any other MDA/LDA you want, e.g.:

How to: implement “fetch + backup + expire” workflow

The intended workflow described above looks like this:

### setup: do once
echo 0 > ~/.rsync-last-mail-backup-timestamp

cat > ~/bin/new-mail-hook << EOF
#!/bin/sh -e
# index new mail
notmuch new

# auto-tagging rules go here

# backup
backup_start=\$(date +%s)
if rsync -aHAX ~/Mail /disk/backup ; then
    echo "\$backup_start" > ~/.rsync-last-mail-backup-timestamp
fi
EOF
chmod +x ~/bin/new-mail-hook
### repeatable part

# optionally, if needed
# imaparms mark ... --folder "[Gmail]/All Mail" unseen

# every hour, fetch new and expire old mail from two GMail accounts,
# generate new desktop notifications with `notify-send` if some of the commands fail
imaparms for-each --every 3600 --notify-failure \
    --host imap.gmail.com \
      --user account@gmail.com --passcmd "pass show mail/account@gmail.com" \
      --user another@gmail.com --passcmd "pass show mail/another@gmail.com" \
  -- \
    fetch --folder "[Gmail]/All Mail" --maildir ~/Mail/INBOX --new-mail-cmd new-mail-hook \; \
    fetch --folder "[Gmail]/Spam" --maildir ~/Mail/spam  \; \
    delete --folder "[Gmail]/All Mail" --folder "[Gmail]/Spam" --folder "[Gmail]/Trash" \
      --older-than-timestamp-in ~/.rsync-last-mail-backup-timestamp \
      --older-than 7

# note how new spam does not invoke `new-mail-hook`

You can check your command lines by running with --very-dry-run option, for the command above it prints:

# every 3600 seconds, for each of
... user account@gmail.com on host imap.gmail.com port 993 (SSL)
... user another@gmail.com on host imap.gmail.com port 993 (SSL)
# do
... in '[Gmail]/All Mail': search (UNSEEN), perform fetch, mark them as SEEN
... in '[Gmail]/Spam': search (UNSEEN), perform fetch, mark them as SEEN
... in '[Gmail]/All Mail', '[Gmail]/Spam', '[Gmail]/Trash': search (SEEN BEFORE 1-Jan-1970) {dynamic}, perform delete

Personally, I have a separate script exec-invoking imaparms (see the terminal recording above) for each mail service I use, my window manager spawns a terminal window with tmux attach -t subs on startup while I have the following at the end of my ~/.tmux.conf:

# create new session named "subs" with the first window named "shell"
new-session -s subs -n shell
# set remain-on-exit for all windows in this session by default
set-option  -t subs -g remain-on-exit on
# add new windows running imaparms instances
new-window -t :2 -n mail imaparms-fetch-mine
new-window -t :3 -n gmail imaparms-fetch-gmail
# ... and so on

This way, if I need to fetch mail from one of the services immediately (e.g. for 2FA tokens sent via email) I just navigate to the respective tmux window and hit Ctrl+C there.

How to: run imaparms in parallel with fetchmail or similar

You can run imaparms fetch with --any-seen --unflagged command line options instead of the implied --unseen --any-flagged options, which will make it use the FLAGGED IMAP flag instead of the SEEN IMAP flag to track state, allowing you to run it simultaneously with tools that use the SEEN flag, like fetchmail, getmail, or just another instance of imaparms (using the other flag).

I.e. if you are really paranoid, you can this feature to check files produced by fetchmail and imaparms fetch against each other and then simply delete duplicated files. Or you can use it to run two instances of imaparms on two separate machines and only expire old mail from the server after it was successfully backed up onto both machines.

Running in parallel with fetchmail using maildrop MDA for both fetchmail and imaparms can be implemented like this:

### setup: do once
echo 0 > ~/.rsync-last-mail-backup-timestamp

mkdir -p ~/Mail/INBOX/{new,cur,tmp}
mkdir -p ~/Mail/spam/{new,cur,tmp}
mkdir -p ~/Mail/INBOX.secondary/{new,cur,tmp}

cat > ~/.mailfilter << EOF
DEFAULT="\$HOME/Mail/INBOX"
EOF

cat > ~/.mailfilter-spam << EOF
DEFAULT="\$HOME/Mail/spam"
EOF

cat > ~/.mailfilter-secondary << EOF
DEFAULT="\$HOME/Mail/INBOX.secondary"
EOF

cat > ~/bin/new-mail-hook-dedup << EOF
#!/bin/sh -e
# deduplicate
jdupes -o time -O -rdN ~/Mail/INBOX ~/Mail/INBOX.secondary

# continue as usual
exec ~/bin/new-mail-hook
EOF
chmod +x ~/bin/new-mail-hook-dedup

secondary_common=(--host imap.gmail.com \
  --user account@gmail.com --passcmd "pass show mail/account@gmail.com" \
  --user another@gmail.com --passcmd "pass show mail/another@gmail.com")

# prepare by unflagging all messages
imaparms mark "${secondary_common[@]}" --folder "INBOX" unflagged
### repeatable part
# run fetchmail daemon as usual, fetching new mail into the secondary maildir every hour
fetchmail --mda "maildrop ~/.mailfilter-secondary" -d 3600

# every 15 minutes
# - fetch new mail using FLAGGED flag for tracking state from "[Gmail]/All Mail",
# - fetch new mail using SEEN flag for tracking state from "[Gmail]/Spam",
# - expire old backed up messages marked both SEEN (by fetchmail) and FLAGGED (by imaparms) from "[Gmail]/All Mail",
# - expire old backed up messages marked as SEEN (by imaparms) from "[Gmail]/Spam",
# - clean any messages older than 7 days (regardless of their flags) from "[Gmail]/Trash".
# - generate new desktop notifications with `notify-send` if some of the commands fail
imaparms for-each --every 900 --notify-failure \
    "${secondary_common[@]}" \
  -- \
    fetch --folder "[Gmail]/All Mail" --mda maildrop --new-mail-cmd new-mail-hook --any-seen --unflagged \; \
    fetch --folder "[Gmail]/Spam" --mda "maildrop ~/.mailfilter-spam" \; \
    delete --seen --flagged --folder "[Gmail]/All Mail" \
      --older-than-timestamp-in ~/.rsync-last-mail-backup-timestamp \
      --older-than 7 \; \
    delete "[Gmail]/Spam" \
      --older-than-timestamp-in ~/.rsync-last-mail-backup-timestamp \
      --older-than 7 \; \
    delete --any-seen --any-flagged --folder "[Gmail]/Trash" \
      --older-than 7

# note how new spam does not invoke `new-mail-hook`

See also

See the usage section for explanation of used command line options.

See the examples section for more examples.

Why would you even want to use any of this, isn’t GMail good enough?

Remember the time when YouTube and Facebook showed you only the posts of people you were subscribed to? After they locked your in by becoming a monopoly by providing fairly good social networking services for free for years (selling under cost is textbook monopolistic behaviour) they started showing “promoted” posts (i.e. advertisements) in your feed so that they could provide cheap and very effective advertisement services for companies at your expense. Then, when advertisers were locked in, they started fleecing them too.

Now your subscriptions are just one of the inputs to their algorithms that are designed to make you waste as much time as possible on their platforms (while keeping you satisfied or addicted just enough so that you wouldn’t just leave), and advertisers’ ad postings are just inputs to their algorithms that are designed to waste as much of the advertiser’s money as possible (being just effective enough to make them spend more).

(The process which Cory Doctorow calls “Enshittification”.)

Remember the time when most people run their own mail servers or had their employers run them and you yourself got to decide which messages should go to INBOX and which should be marked as spam? Today, Google provides email services for free, and so >70% of all e-mails originate from or get delivered to Google servers (GMail, GMail on custom domains, corporate GMail). Now it’s Google who decides which messages you get to see and which vanish into the void without a trace.

Which, as a recipient, is highly annoying if you frequently get useful mail that GMail marks as spam or just drops (happens all the time to me). And, as a sender, is highly annoying when you need to send lots of mail. Just go look up “Gmail Email Limits” (on a search engine other than Google). It’s a rabbit hole with lots of ad-hoc rules on just how much mail you can send before GMail decides to just drop your messages, yes, drop, not mark as spam, not reject, they will drop your mail and tell neither you nor the recipient anything at all.

Moreover, they are now working towards making their INBOX into an algorithmically generated feed with “important” messages being shown first. It’s easy to see where this is going.

Luckily, while Google is working hard to discourage you from using and/or make open mail protocols unusable, IMAP is still #1 protocol for accessing and managing mail, and setting up your own mail server gets easier every year, so they can’t just stop supporting it just yet (but they are doing their best).

But, objectively, GMail — when it works — is a very nice Mail User Agent (aka MUA, aka email client, aka mail app) with an integrated full-text search engine and a labeling system.

Meanwhile, other modern MUAs like Thunderbird, Sylpheed, or K-9 Mail are designed to be IMAP and SMTP clients first, full-text search and tagging/labeling systems second (if at all). Which is to say, they suck at searching and tagging mail. Especially, since doing those things over IMAP is annoyingly slow, especially when your IMAP server is GMail which very much does not want you to use IMAP (after all, with a MUA working over IMAP, it’s the MUA that decides how to sort and display your INBOX, not Google, and they hate they can’t turn the order of messages in your INBOX into something they can sell).

However, there exists a bunch of MUAs that can do full-text mail search and tagging so well and so blazingly fast that they leave GMail in the dust (from a technical standpoint, given an index, full-text search >10x faster than GMail on a single-core of 2012-era laptop with an SSD is pretty easy to archive, simply because your SSD is much closer to you than GMail’s servers).

Examples of such awesome MUAs that I’m aware of, in the order from simplest to hardest to setup:

However, to use these awesome MUAs you need to download your mail and save it in Maildir format on your hard disk first.

Which is where imaparms and similar tools like fetchmail, getmail, offlineimap, imapsync, and etc come in.

Also, if GMail suddenly decides to take your mail hostage by locking you into their web-mail and disabling IMAP access, which seems more and more plausible every year, having a local copy of most of your mail will make it much easier to switch away. (Seems unrealistic to you? This actually happened to me with one of the email providers I used before (not GMail, not yet). They basically tried to force me to go through a KYC procedure to allow me to continue using IMAP, but because I had local backups, I just switched all the services that referenced that email address to something else and simply stopped using their service. Are you sure Google wouldn’t do this?)

See “The Homely Mutt” by Steve Losh for a long in-detail explanation on how this setup in general is supposed to work. It describes a setup specifically tailored for mutt + notmuch + offlineimap + msmtp and the actual configs there are somewhat outdated (it was written in 2012) and much more complex than what you would need with, e.g. sup + imaparms + msmtp, but it gives a good overview of the idea in general. Functionally, imaparms takes place offlineimap in that article.

Personally, I use notmuch with Emacs, which requires almost no setup if you have a well-configured Emacs already (and effectively infinite amounts of setup otherwise).

Also, see “Sup” article on ArchWiki for how to setup sup.

(Also, in theory, Thunderbird also supports operation over Maildir, but that feature is so buggy it’s apparently disabled by default at the moment.)

Google’s security theater

GMail docs say that IMAP and SMTP are “legacy protocols” and are “insecure”. Which, sure, they could be, if you reuse passwords. But them implying that everything except their own web-mail UI is “insecure” is kinda funny given that they do use SMTP to transfer mail between servers and signing in with Google prompts exists. I.e. you can borrow someone’s phone, unlock it (passcode? peek over their shoulder or just get some video surveillance footage of them typing it in public; fingerprint? they leave their fingerprints all over the device itself, dust with some flour, take a photo, apply some simple filters, 3D-print the result, this actually takes ~3 minutes to do if you know what you are doing), ask Google to authenticate via prompt. Done, you can login to everything with no password needed. And Google appears to give no way to disable Google prompts if your account has an attached Android device. Though, you can make Google prompts ask for a password too, but that feature needs special setup. Meanwhile, “legacy” passwords are not secure, apparently?

So to use imaparms with GMail you will have to enable 2FA in your account settings and then add an application-specific password for IMAP access. I.e., instead of generating a random password and giving it to Google (while storing it in a password manager that feeds it to imaparms), you ask Google to generate a random password for you and use that with imaparms.

To enable 2FA, even for very old accounts that never used anything phone or Android-related, for no rational reasons, GMail requires specifying a working phone number that can receive SMS. Which you can then simply remove after you copied your OTP secret into an authenticator of your choice. Sorry, why did you need the phone number, again?

Ah, well, Google now knows it and will be able track your movements by buying location data from your network operator. Thank you very much.

In theory, as an alternative to application-specific passwords, you can setup OAuth2 and update tokens automatically with mailctl, but Google will still ask for your phone number to set it up, and OAuth2 renewal adds another point of failure without really adding any security if you store your passwords in a password manager and use --passcmd option described below to feed them into imaparms.

That is to say, I don’t use OAuth2, which is why imaparms does not support OAuth2.

Your emails will eventually get stolen anyway

Note that Snowden revelations mean that Google and US Government store copies of all of your correspondence since 2007-2009 (it depends on your mail provider) even if you delete everything from all the servers.

And they wiretap basically all the traffic going though international Internet exchanges because they wiretap all underwater cables. Simply because they can, apparently? (If you think about it, there is absolutely no point to doing this if you are trying to achieve their stated signal-intelligence goals. Governments and organized crime use one-time-pads since 1950s. AES256 + 32 bytes of shared secret (+ 8 bytes of plain-text session key + 4 bytes of plain-text IV) + some simple steganography and even if the signal gets discovered, no quantum-computer will ever be able to break it, no research into quantum-safe cryptography needed. So, clearly, this data collection only works against private citizens and civil society which have no ways to distribute symmetric keys and thus have to use public-key cryptography.)

Globally, >70% of all e-mails originate from or get delivered to Google servers (GMail, GMail on custom domains, corporate GMail).

Most e-mails never gets E2E-encrypted at all, (100 - epsilon)% (so, basically, 100%) of all e-mails sent over the Internet never get encrypted with quantum-safe cryptography in-transit.

So, eventually, US Government will get plain-text for almost everything you ever sent (unless you are a government official, work for well-organized crime syndicate, or you and all your friends are really paranoid).

Which means that, eventually, all that mail will get stolen.

So, in the best case scenario, a simple relatively benign blackmail-everyone-you-can-to-get-as-much-money-as-possible AI will be able organize a personal WikiLeaks-style breach, for every single person on planet Earth. No input from nefarious humans interested in exploiting personally you required. After all, you are not that interesting, so you have nothing to fear, nothing to hide, and you certainly did not write any still-embarrassing e-mails when you were 16 years old and did not send any nudes of yourself or anyone else to anyone (including any doctors, during the pandemic) ever.

It would be glorious, wouldn’t it?

(Seriously, abstractly speaking, I’m kinda interested in civilization-wide legal and cultural effects of every embarrassing, even slightly illegal and/or hypocritical thing every person ever did relentlessly programmatically exploited as blackmail or worse. Non-abstractly speaking, why exactly do governments spend public money to make this possible? After all, hoarding of exploitable material that made a disaster after being stolen worked so well with EternalBlue, and that thing was a fixable bug, which leaked blackmail is not.)

That is to say, as a long-term defense measure, this tool is probably useless. All your mail will get leaked eventually, regardless. Against random exploitations of your mail servers imaparms is perfect.

Also, imaparms is a very nice fast mail fetcher, regardless of all of this.

Comparison to

fetchmail and getmail

imaparms fetch

fdm

A better explanation of what fdm does.

imaparms fetch

IMAPExpire

imaparms delete

offlineimap, imapsync, and similar

License

GPLv3+.

Usage

imaparms

A handy Swiss-army-knife-like utility for performing batch operations on messages residing on IMAP servers. Logins to a specified server, performs specified actions on all messages matching specified criteria in all specified folders, logs out.

imaparms list

Login, perform IMAP LIST command to get all folders, print them one per line.

imaparms count

Login, (optionally) perform IMAP LIST command to get all folders, perform IMAP SEARCH command with specified filters in each folder, print message counts for each folder one per line.

imaparms mark

Login, perform IMAP SEARCH command with specified filters for each folder, mark resulting messages in specified way by issuing IMAP STORE commands.

imaparms fetch

Login, perform IMAP SEARCH command with specified filters for each folder, fetch resulting messages in (configurable) batches, feed each batch of messages to an MDA, mark each message for which MDA succeeded in a specified way by issuing IMAP STORE commands.

imaparms delete

Login, perform IMAP SEARCH command with specified filters for each folder, delete them from the server using a specified method.

imaparms for-each

For each account: login, perform other subcommands given in ARGs, logout.

This is most useful for performing complex changes --every once in while in daemon mode. Or if you want to set different --folders for different subcommands but run them all at once.

Except for the simplest of cases, you must use -- before ARGs so that any options specified in ARGs won’t be picked up by for-each. Run with --very-dry-run to see the interpretation of the given command line.

All generated hooks are deduplicated and run after all other subcommands are done. E.g., if you have several fetch --new-mail-cmd filter-my-mail as subcommands of for-each, then filter-my-mail will be run once after all other subcommands finish.

Notes on usage

Examples

Now, assuming the following are set:

common=(--host imap.example.com --user account@example.com --passcmd "pass show mail/account@example.com")
common_mda=("${{common[@]}}" --mda maildrop)
gmail_common=(--host imap.gmail.com --user account@gmail.com --passcmd "pass show mail/account@gmail.com")
gmail_common_mda=("${{gmail_common[@]}}" --mda maildrop)