Email

Sovereign can send email over SMTP, and uses it to tell administrators when something needs their attention. It’s off by default, and stays off until you give it a server to send through.

Turning It On

Setting a host turns email on. There’s no separate on/off switch, because a second switch only creates a state where mail is “enabled” but has nowhere to go.

Sovereign__Notification__Email__Host=smtp.example.com
Sovereign__Notification__Email__Port=587
Sovereign__Notification__Email__Security=StartTls
Sovereign__Notification__Email__Username=sovereign@example.com
Sovereign__Notification__Email__Password=<smtp-password>
Sovereign__Notification__Email__FromAddress=sovereign@example.com

Leave Sovereign__Notification__Email__Host empty and nothing is sent. Nothing else in Sovereign changes, and an install that never configures email is fully supported.

Environment Variable	Description	Default	Sensitive
`Sovereign__Notification__Email__Host`	SMTP server hostname. Empty disables email entirely	(empty)
`Sovereign__Notification__Email__Port`	SMTP server port	`587`
`Sovereign__Notification__Email__Security`	Transport security: `None`, `StartTls`, or `SslOnConnect`	`StartTls`
`Sovereign__Notification__Email__Username`	Username for SMTP authentication. Empty means no authentication is attempted	(empty)
`Sovereign__Notification__Email__Password`	Password, app password, or API token for SMTP authentication	(empty)	✓
`Sovereign__Notification__Email__FromAddress`	Address messages are sent from. Required once a host is set	(empty)
`Sovereign__Notification__Email__FromName`	Display name paired with the from address	`Sovereign`
`Sovereign__Notification__Email__TimeoutSeconds`	Seconds a single connect, authenticate, and send may take before it’s abandoned	`30`
`Sovereign__Notification__Email__RetentionDays`	Days a sent-message record is kept before the daily maintenance job removes it	`90`

Everything sits under Sovereign__Notification__, alongside the digest settings further down the page.

Choosing a Port and Security Mode

The port and the security mode go together, and getting the pairing wrong is the most common reason a first send fails.

Port	Security	What happens
`587`	`StartTls`	Connects in the clear, then upgrades to TLS. The usual choice, and what most providers document as “submission”
`465`	`SslOnConnect`	Negotiates TLS immediately on connecting
`25`	`None`	Plaintext. Only appropriate for a relay on your own network

There’s no automatic mode, because a relay that didn’t advertise STARTTLS would then be sent your credentials in plaintext. Pick the mode your provider documents.

Many providers require an app password rather than your account password, and some require the from address to match the authenticated account exactly. Check your provider’s SMTP documentation before assuming a rejected login is a Sovereign problem.

The Email Admin Page

Sign in as an administrator and open Settings, then System > Email. The page shows the relay this server will send through, a way to send a test message, and every message it has sent.

The test send waits for the SMTP server and shows you what it said, so a rejected credential or an unreachable host comes back as the server’s own error text rather than a generic failure. That’s the fastest way to tell a wrong password from a wrong port.

If the page says email is disabled, Sovereign__Notification__Email__Host didn’t reach the server. Confirm the variable name uses double underscores, and remember that configuration is read at startup, so a change needs a restart.

Sent Messages

Every message Sovereign accepts is recorded, whether or not it arrived. The table on the Email page lists the recipients, the subject, how many attempts were made, and the relay’s own error on the most recent failure. Expand a row to see the sender and the message body.

A message is one of four things:

Sent - handed to the SMTP server without error.
Queued - accepted, and waiting on an attempt or a retry.
Failed - every attempt failed. The error column says why.
Disabled - email wasn’t configured when the message came up, so nothing was sent.

Records are kept for Sovereign__Notification__Email__RetentionDays days (90 by default) and then removed by the daily database maintenance job. Set it to 0 to keep them indefinitely.

Validation at Startup

Once a host is set, Sovereign checks the rest of the section before it finishes starting:

The port has to be between 1 and 65535.
FromAddress has to be present and a parseable address. Most relays reject a message with no sender, and finding that out at startup is better than finding it out the first time something tried to send.
The timeout has to be greater than zero.
While the digest is enabled, its window and its client-error threshold both have to be greater than zero.

A username or password alongside Security=None would send the credentials in the clear. In development that’s logged as a warning. Anywhere else it stops the server starting, so use StartTls or SslOnConnect with any relay that needs credentials.

What Sovereign Sends

Four messages are automatic.

When somebody signs in with Google or Microsoft for the first time, Sovereign creates their account with no privileges and holds it for approval, and nothing about that is visible until an administrator happens to open the user list. With email configured, every administrator who has an address on their account gets told.

The second is a change in the server’s license standing: a server that had a license and has lost it, or one that’s sharing its license with another server. An all-clear follows when the problem goes away. A new server that has never been registered doesn’t send one.

The third is a volume running out of room. Sovereign checks free space on the volumes it uses once an hour, and mails administrators when one drops to a warning level (10% or 5 GiB free, whichever comes first) or a critical one (5% or 1 GiB). It’s sent when a volume crosses a level, not for every hour it stays there, and a volume that recovers gets an all-clear. The Sovereign__Storage__* settings in the Configuration Overview move those thresholds, and setting all four to 0 turns the notice off.

The fourth is the daily digest of what went wrong overnight.

Administrators without an email address on their account are skipped, so if nobody has one, nobody is notified. Add an address to your admin account under Account, then Profile.

Messages are plain and short. Subjects are prefixed with [Sovereign] so they’re easy to filter, and no message contains a link, so there’s nothing in one to click through.

The Daily Digest

A failed library sync, or a run of errors coming back from your Roku, is the kind of thing you only find out about by opening Settings and looking. At 04:00 UTC each day Sovereign gathers both and mails administrators one summary.

On a day with nothing to report, nothing is sent. A daily “all clear” soon gets filtered into a folder nobody opens, and the one message that mattered goes with it.

A message reads roughly like this:

Subject: [Sovereign] Daily digest: 3 job failures, 41 client errors

Covering 2026-09-04 04:00 to 2026-09-05 04:00 UTC.

Scheduled jobs: 3 failures across 2 jobs.
MovieCredits-job: 2 failures, last at 2026-09-05 03:00 UTC. HttpRequestException: name or service not known
http://sonarr:8989: 1 failure, last at 2026-09-04 22:15 UTC. SocketException: connection refused

Client errors: 41 reports from 6 devices.
By category: Playback 30, Network 9, Rendering 2.
Most frequent: SHAKA_ERROR_3016 22, TypeError 11, NotAllowedError 8.

The full detail is in the Sovereign web interface: Settings, then Jobs for the job history, or Client Errors for the reports.

It counts rather than lists. Both sources arrive in bursts, so a client stuck in a retry loop files dozens of reports a minute, and a job that failed at midnight will usually fail again at one. A line per row would bury the fact that only two things are wrong.

Environment Variable	Description	Default
`Sovereign__Notification__Digest__Enabled`	Whether the digest is sent at all	`true`
`Sovereign__Notification__Digest__WindowHours`	How far back each digest looks	`24`
`Sovereign__Notification__Digest__ClientErrorThreshold`	Client error reports needed within the window before the digest mentions them	`5`

The threshold is there because a handful of client errors is the background noise of any fleet, and a message about three of them is a message you’ll learn to ignore. Set it to 1 if you’d rather see every one. It only applies to the client half: a failed scheduled job always earns a digest on its own.

Setting Sovereign__Notification__Digest__Enabled=false turns the digest off and leaves email working for everything else. An empty Sovereign__Notification__Email__Host turns it off too, along with the rest of Sovereign’s mail.

Keep WindowHours at 24 unless you have a reason not to. The digest is sent daily, so a shorter window leaves a gap that nothing ever reports, and a longer one repeats what yesterday’s message already covered.

Sending Is Best Effort

Automatic messages are queued and sent in the background, up to three attempts with a growing gap between them. A slow or unreachable server never delays whatever triggered the message, and a social sign-in still completes normally whether or not the notice went out.

A message still queued when the server shuts down survives: it’s held in the database, and Sovereign picks it back up on the next start with whatever attempts it had left. It doesn’t get a fresh three, so a message nothing can deliver won’t retry forever.

Sovereign can tell whether the relay accepted a message, not whether it reached an inbox. A relay that drops mail without reporting an error looks the same as one that delivers it.

Titles, artwork, people and descriptions shown in screenshots are fictional and were created for illustration. Sovereign doesn't include or supply any media: it plays the library you bring.