Automatic Junk-Mail Cleaner (ADMailCleaner)
A service that watches several IMAP mailboxes in a loop and bins unwanted mail based on the sender — no more cleaning out the inbox by hand.
The problem
Some mailboxes steadily pile up junk from the same handful of senders — newsletters I never unsubscribed from, automated notifications, promotions. Cleaning them out by hand is tedious, and it’s easy to keep putting it off.
How it works
A containerized Python service loops continuously over several IMAP mailboxes (both
self-hosted and Gmail), and for each configured sender marks matching mail as read and
moves it to Trash. The matching rules are flexible — an exact address, a whole domain, or
a substring in the sender — with IMAP search doing a coarse first pass and the real
From: header re-checked before acting, to avoid false positives.
A bug that wasn’t the project’s fault — it was the host’s
The most instructive moment wasn’t in this service’s code at all, but in the
infrastructure hosting it. At one point every Docker container on the machine
suddenly lost internet access — not just this service, the entire home-automation stack.
The cause: the firewall rules allowing outbound traffic (FORWARD) only covered Docker’s
default network interface, while every network created by individual Docker Compose
projects needed its own — a silent detail, no explicit errors, just connections that hung.
The fix was restarting the Docker engine to regenerate the full, correct set of firewall rules, with this service (and one other critical one) additionally pinned to also use the default network interface as a fallback. A useful reminder: when every service breaks at once, the problem is rarely in any one of them.
Status
Active and in production, running on a native Linux Docker engine (migrated off Docker Desktop for reliability), with several mailboxes connected at once. Possible improvements: subject-keyword matching too, a periodic summary of what was moved, reloading configuration without restarting the container.
Stack
Python · IMAP · Docker · WSL2