External integration - Paperless-ngx

Development
1

cover-paperless

Hi everyone!

The self-hosting series continues, for those who have a NAS or a home server. After the Sonarr & Radarr movies (which I loved doing), it’s time for papers: Paperless-ngx, which swallows scanned bills and sorts them automatically. Now, Gladys knows when the mail arrives.

What it does

  • A Paperless-ngx device: online, total documents, documents in the inbox (to be sorted), added today, tasks in progress and failed, number of correspondents, types and tags, free storage, version and available update.
  • Three triggers: « New document » (filterable by correspondent and type), « New document with a tag » and « Document processing failure ».
  • A « Mail to sort » widget: the number of documents to sort and the latest titles.
  • Read-only: Gladys doesn’t touch anything in Paperless-ngx.
  • In French, English, German and Spanish.

The cool part

EDF bill received (correspondent EDF, type Bill) → notification with the title
Document tagged Urgent → the entrance light turns orange
Saturday 10 a.m., if there’s still mail to sort → gentle reminder

Installation

:warning: Gladys 5.1 minimum.

It will arrive in the store at the next indexer run. In the meantime: Integrations → Install from GitHub, with GitHub - guim31/gladys-paperless: Paperless-ngx document management for Gladys Assistant · GitHub

  1. In Paperless-ngx: your name in the top right → My profile → API authentication token (create it if it doesn’t exist), and copy it. An administrator’s token also gives free storage.
  2. In Gladys: the Paperless-ngx address (the one from your browser) and the token, then Test connection.
  3. Discovery tab: add the device.

Honest small reservations

  • Single instance, read-only: no sending or tagging from Gladys.
  • The integration sees what the token user sees: their documents and those shared with them.
  • Filters compare exact names (EDF does not match edf), and a tag added manually later triggers nothing.
  • Paperless-ngx 1.x is not supported.
  • Tested against real Paperless-ngx 2.20.6 and 3.3.1, launched for the occasion from the official images and filled with documents (including a broken PDF, for the processing failure), with an administrator token and a simple token. Not yet seen in a real Gladys installation, nor behind a reverse proxy or a SSO, and the announcement of an update could not be seen in real life: your feedback is welcome.

Like the previous ones, developed with Claude Code. Independent project, not affiliated with Paperless-ngx.

Repository: GitHub - guim31/gladys-paperless: Paperless-ngx document management for Gladys Assistant · GitHub