← All projects
Active August 2026

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.

PythonDockerIMAPWSL2Automation

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