Quarantine Sentinel: a second opinion for Proxmox Mail Gateway

Our Proxmox Mail Gateway (PMG) puts a small but steady number of legitimate mails into quarantine. In the run I am using as an example below, 3 of 856 quarantined messages were mail somebody actually wanted. The way we dealt with that until now: every colleague checks their own spam quarantine by hand. Which in practice means irregularly, or not at all, and with a seven day retention a mail can be gone before anyone looks.

Quarantine Sentinel is a small Python script that does that sweep instead. It logs into PMG read-only, pulls every quarantined message across all users for a configurable lookback window and asks an LLM to judge each one against PMG's own headers, the SpamAssassin rule hits and a text excerpt of the body. Anything the model is confident is legitimate mail shows up in a digest. The script only ever reads from PMG: it leaves the spam scoring alone and never releases mail by itself, so somebody still has to look at the digest and click Deliver.

The code lives on GitHub: github.com/mgeha/quarantine-sentinel

What it does

• Authenticates to a PMG node via ticket-based auth (PMG has no API tokens)
• Fetches quarantined messages for all users within a configurable lookback window
• Scores each new message against an LLM (Ollama, OpenAI or Anthropic) to flag likely false positives
• Caches every verdict in a local SQLite database, so a mail is never re-scored on the next run
• Prints a digest of probable false positives, with the model's reasoning and PMG's own spam score for context

Prerequisites

• Python 3.11+ and uv
• A PMG node (tested against 9.x)
• An LLM backend: a local Ollama instance, or an API key for OpenAI or Anthropic

Before anything else, create a dedicated PMG account for the poller and give it the Auditor role, which is the read-only access level it needs. Don't reuse root. PMG's account types and roles are documented under User Management in the admin guide.

Installation

The script ships as a single file with PEP 723 inline dependency metadata, so there is no virtualenv to set up. uv reads the dependency block at the top of the file and installs what it needs on the fly.

Using Ollama instead? Nothing extra to install. Set backend = "ollama" in config.toml and run the same command. For OpenAI, run with uv run --with openai quarantine_sentinel.py, since openai isn't in the inline dependency block by default.

Configuring it

Everything lives in config.toml, which is deliberately git-ignored: it holds credentials and real mail metadata and should never end up in a repo. config.toml.example is a fully commented starting point. These are the parts worth understanding before your first run:

A few top-level settings control how aggressively it works:

• lookback_days: How far back into quarantine to look (PMG's default retention is 7 days)
• confidence_threshold: Minimum ham-confidence (0.0 to 1.0) for a mail to make it into the digest
• max_mails_per_run: Hard cap on LLM calls per run, a safety valve against runaway API cost
• max_workers: How many mails to score in parallel (lower it for Ollama on modest hardware)
• rcpt_ignore: Recipients (shared mailboxes, mailing lists, monitoring addresses) skipped entirely, before any mail is even fetched
• policy_file: Your own scoring rules, replacing the shipped default_policy.md

For rcpt_ignore there is a small interactive helper, so you don't have to hand-type addresses:

It lists the recipients currently sitting in quarantine and lets you add any of them to the ignore list on the spot.

Your first run

Here is an actual run against our own gateway. Sender names, domains, hostnames and mail IDs are replaced, everything else is verbatim:

Everything above the threshold is worth a look in the PMG web UI. Everything below it stays in quarantine unless you go and dig manually. Releasing happens in PMG itself, and the report prints both paths at the bottom so nobody has to look them up.

That output also shows one of the rough edges. The press release appears twice, once per recipient, and the two copies came back at 92% and 85%. Same mail, same headers, different number. It doesn't matter much when both are above the threshold, but the confidence value is not something to read too precisely.

Of the 856 mails in scope, 797 came out of quarantine_sentinel.db and only 59 were sent to the API. That ratio is what makes a cron job every 30 minutes affordable: after the first run you only ever pay for genuinely new mail.

Tuning what counts as "ham"

default_policy.md holds the actual spam/ham heuristics: which SpamAssassin rules count as strong evidence (RBL hits, BAYES_99), which are explicitly not enough on their own (a bare SPF/DKIM failure, HTML_MESSAGE), and how brand impersonation on unrelated infrastructure gets caught.

One rule needed spelling out. KAM_MARKSPAM contributes 10 points and it fires because PMG has already classified the mail as spam. Hand that to the model as evidence and it will agree with the gateway every single time, which makes the whole exercise pointless. The policy tells it to disregard the rule, and you can watch that land in the output above: "the gateway's own quarantine decision being audited, circular evidence that must be disregarded".

If your mail has quirks the default policy doesn't account for, such as internal domains or a vendor with a permanently broken SPF record, copy the file, edit your copy and point at it with policy_file = "local/my_policy.md".

(local/ is git-ignored, which makes it a convenient place for a policy that names your internal domains.) A configured policy replaces the default instead of merging with it, and relative paths resolve against the config file's directory, so a cron or systemd run still finds it.

Verdicts are cached by mail ID only, so editing the policy doesn't re-score anything already in the database. After a real policy change, delete quarantine_sentinel.db.

Before you point this at real mail

A cloud LLM backend (OpenAI, Anthropic) receives message metadata, authentication results, spam-rule hits and a body excerpt bounded by body_max_chars. Attachments are never sent. If that conflicts with your data protection requirements, run an on-premises Ollama model instead and nothing leaves your infrastructure.

With a cloud backend you want a data processing agreement with the provider in place before this touches real mailboxes. quarantine_sentinel.db holds quarantined-mail metadata and the model's verdicts, so it belongs on storage with restricted access.

Three hits out of 856 is not a dramatic rate, and a cautious policy leaves borderline mail sitting below the threshold. But those three entries are two real mails, a press release and a forwarded enquiry about an advertising deal, and neither of them would have been found before retention deleted it.