Notifications

Off unless NOTIFY_URL is set. Everything still goes to the container log. With a URL, plungarr sends digests to one receiver, and each category has its own cadence.

Tested against a live receiver: ntfy, startup message and immediate digest, September 2026. The other formats follow each service's published API and are covered by unit tests, but have not yet been exercised against a real receiver. If one misbehaves, open an issue with the error line from the log.

Receivers

Pick a format with NOTIFY_FORMAT. NOTIFY_TOKEN is optional. NOTIFY_EXTRA_JSON is a JSON object merged into every payload for receiver-specific fields.

Format	URL to set	Payload and auth
`discord`	The channel's webhook URL	`{"content"}`. Long digests are split at 2000 characters at line boundaries. Extra JSON can set `username`.
`slack`	The incoming-webhook URL	`{"text"}`.
`ntfy`	The topic URL, e.g. `https://ntfy.sh/your-topic`	Raw text with a `Title` header. Token becomes a Bearer header. Extra JSON fields become headers, e.g. `{"Priority":"4","Tags":"tv"}`. Digests over 4000 bytes are sent as numbered parts, because ntfy turns a longer message into an `attachment.txt`.
`gotify`	`https://host/message`	`{"title","message","priority"}`. Token is sent as `X-Gotify-Key`. Extra JSON can override `priority`.
`apprise`	An Apprise API notify URL with the key in the path	`{"title","body","type"}`. Token becomes a Bearer header. For the stateless endpoint put `urls` in extra JSON.
`json` (default)	Anything that accepts a POST	`{"source":"plungarr","title","text","items":[…]}`. Token becomes a Bearer header. For Home Assistant, n8n, or your own script.

Categories and cadence

Each takes immediate, daily, weekly, monthly, or none.

Setting	Carries	Default
`NOTIFY_ATTENTION`	Items plungarr refuses to touch: unrecognised blocks, sample flags, mapping mismatches, a wedged SABnzbd head	immediate
`NOTIFY_ERRORS`	API failures, cycle errors, state-save failures	immediate
`NOTIFY_ACTIONS`	Every import, removal, blocklist, replacement search, stalled and doomed deletion	daily
`NOTIFY_PROBLEMS`	Chronic failures from the history review	daily
`NOTIFY_CORRUPTION`	Suspect library files from the daily review	weekly
`NOTIFY_SUMMARY`	“What plungarr did” as totals for the period, no per-item lines	none
`NOTIFY_HEARTBEAT`	“plungarr alive” line even when nothing else happened	none

Timing and reminders

Immediate batches within one cycle and sends once at the end of it, so thirty rejections arrive as one message.
Digests fire at NOTIFY_DIGEST_HOUR (default 8, container local time), on NOTIFY_DIGEST_DAY (default monday) for weekly and NOTIFY_DIGEST_DAY_OF_MONTH (default 1) for monthly. Categories sharing a slot are merged into one message with a section each. A window that passed while the container was down goes out on the next cycle.
Reminders. An attention item or repeating error is sent once when first seen and again only after NOTIFY_REMIND_DAYS (default 7; 0 disables). This is the guard against a pile of items nobody noticed.
Startup. One message when the container starts, listing apps, the stall watcher state, and the cadence settings, so a bad URL or token shows up in seconds. The log line NOTIFY-STARTUP confirms it went.
Delivery failures log NOTIFY-ERROR and are retried next cycle. They never block queue processing. Every successful delivery logs NOTIFY-SENT.
Dry run builds the digest text, logs it, and never posts.

What a digest looks like

plungarr: 2 need attention, 5 action(s)

## Needs attention (2)
- [sonarr] Example.Kids.Show.S02E02.720p.WEB — flagged as a sample; left untouched (set SAMPLE_ACTION=replace or discard to auto-clear)
- [sonarr] Example.Series.S05.720p.BluRay — archive not extracted; left untouched (set ARCHIVE_ACTION=replace or discard to auto-clear)

## Actions taken (5)
- [sonarr] IMPORTED Example.Show.S02E04.1080p.WEB-DL — 1 file(s) sent to ManualImport
- [sonarr] REMOVED (discarded, no replacement search) Example.Show.S01E35.1080p.WEB-DL — not an upgrade for the existing file
…

Every line names the setting that would let plungarr act on it automatically, so the digest doubles as a configuration hint.

Trying it in ten minutes

Pick a random topic name and subscribe to it at https://ntfy.sh/that-name in a browser or the ntfy app.
Set NOTIFY_URL to that URL and NOTIFY_FORMAT to ntfy, restart plungarr.
Expect “plungarr online” within seconds, then a “Needs attention” message at the end of the first cycle if anything is waiting on you.

Public ntfy topics can be read by anyone who guesses the name, and digests contain release titles, so switch to your own receiver afterwards.