← All projects
Active October 2026

Bollette Auto

A self-hosted system that watches my inbox, automatically downloads household utility bills from provider portals, files them on my home NAS, and extracts their data into a web dashboard — with Telegram notifications.

PythonDockerPlaywrightFastAPISQLiteSelf-hosted

The problem

Every month, the same chore: an email arrives from the provider, log into the portal, download the PDF, rename it, save it to the right folder. Multiply that by electricity, gas, phone and internet and it becomes a tedious, repetitive task — exactly the kind of thing a computer should be doing for me.

What it does

Bollette Auto (“auto bills”) runs in the background inside a small Docker container and, on its own:

  1. Checks the inbox over IMAP (Gmail and other mailboxes) at regular intervals.
  2. Recognises bill emails by their sender.
  3. Gets the PDF — from the attachment, from a link in the email, or from the provider’s portal.
  4. Files it on the NAS in a tidy year/PROVIDER/ structure.
  5. Extracts the data from the PDF into a database so it can be explored.
  6. Notifies the outcome on Telegram — bill downloaded, or an error.

How it works

At its core is an IMAP polling loop: each mailbox gets its own thread that checks for new mail, routes it to the right provider, and triggers the matching scraper. The downloaded PDF is handed to the archiver, which stores it on the NAS (mounted over CIFS) under the folder for that year and provider.

Two download strategies

Three ways a bill arrives

Not every provider behaves the same, and the system has learned them one by one:

A per-provider subject filter keeps policies and notices that come from the same sender from being filed as “receipts”.

What happens to the email

After processing, the email is marked as read and moved to a “processed” folder; those older than twelve months are deleted, but only from that folder, never from the inbox (the monitored mailboxes include my personal Gmail). Identical error notifications aren’t repeated, and stay quiet at night.

Configuration-driven design

A single YAML file describes mailboxes, providers, selectors and notifications. Most providers can be added without touching code; only the “hard” portals — single-page apps with tokens in sessionStorage, unusual APIs — need a small dedicated scraper in Python.

From PDFs to a dashboard

The bills don’t just sit as PDFs in a folder. Each file is parsed (text extraction with pdfplumber) to pull out the amount, billing period, invoice date, consumption and provider, and the data lands in a SQLite database.

On top of that data runs a web dashboard — a separate FastAPI + Uvicorn service with a static frontend and Chart.js charts:

The filters (provider, year, month) are global and persist as you move between tabs.

Security matters

When the TIM session expires

The saved session lasts a few weeks. When it ran out in October, renewing it turned out harder than the first time: the browser Playwright drives gets stuck in an endless reCAPTCHA loop, and even launching the real Chrome with a dedicated profile didn’t help, because TIM silently rejects a login from a brand-new profile. In my everyday Chrome the login works. So the method that reliably works now is to log in there as usual and import the cookies: export them with a browser extension and run a small script that keeps only TIM’s cookies, tests that the session really loads the bills page, and writes the file only if it does. That check exists because an earlier helper had overwritten a good session with a logged-out one. One last detail: the browser identity the scraper presents had to be aligned with the version of Chrome I actually use, or the imported session risked being refused. After the renewal, the October bill downloaded on its own.

Status

In production and still growing: active providers cover electricity, gas, phone, internet, water, home insurance and motorbike tax, and the archive now holds over 280 bills. The system moved from Docker Desktop (which kept failing on reboot) to native Docker inside a Linux distribution on WSL2 on the mini PC, with automatic startup. The latest provider, water (10 October 2026), was just one line of configuration. TIM remains the fragile one: every few weeks the session needs renewing by hand (see above).

Stack

Python · Playwright · IMAP · Docker (WSL2) · SQLite · FastAPI · Synology NAS (CIFS) · Telegram Bot API

What I learned