Astronomy Journal Downloader
A service that watches a mailbox, downloads the PDF issues of an astronomy journal linked in each email, and archives them on the NAS by year — no more doing it by hand every time.
The problem
I periodically get emails with a direct link to an astronomy journal’s PDF issue. Downloading and filing each one by hand, sorted by year, was the classic small repetitive chore — a perfect candidate for automation.
How it works
A small containerized service polls a self-hosted mailbox over IMAP, looking for unread messages with a direct PDF link. For each one it finds: it downloads the file, saves it on the home NAS in a folder named after the year (defaulting to the email’s received date, not whatever’s in the filename), then marks the message as read and moves it to Trash. An optional sender/subject filter lets you restrict the check to a specific source.
The interesting bug: a mail server that doesn’t speak the expected dialect
The tricky part wasn’t the download — it was moving the email to Trash afterwards. The self-hosted IMAP server in use doesn’t support two extensions almost everyone takes for granted: MOVE and UIDPLUS. The first implementation relied on exactly those, and failed silently: the email ended up marked read but stuck in the inbox, never moved.
The fix is to fall back to “plain” IMAP: copy the message into the Trash folder, flag it
\Deleted in the original folder, then run a plain EXPUNGE (not a UID EXPUNGE,
which needs UIDPLUS). A useful reminder: not every mail server, even a self-hosted one,
implements the same extensions — worth checking before writing code that assumes them.
Small safeguards
The service starts up in a dry-run mode (logging only, no real actions) before going into production — a habit that helped validate the filtering logic without risking losing mail by mistake.
Status
Completed and in production: the service checks the mailbox periodically, downloads and archives the PDFs, and correctly marks them as processed. A closed project — it runs without active maintenance.
Stack
Python · IMAPClient · BeautifulSoup · Docker · WSL2