Stashboard SMTP Email Notifications Setup in 4 Steps

If you run Stashboard as your homelab service dashboard, getting Stashboard SMTP email notifications configured correctly is one of the first things worth doing after initial install. Unlike most self-hosted Docker apps, Stashboard applies your email server changes instantly — no container restart needed, no docker compose down, no lost uptime. This guide walks through every field on the Notifications page, explains why your credentials live in the database rather than a .env file, covers the tri-state password field that trips up new users, and shows you exactly how to back up the one Docker volume that stands between you and an unrecoverable configuration. If you haven’t deployed Stashboard yet, start with the Stashboard overview post first.

Why Stashboard SMTP Email Notifications Live in the Database, Not in .env

Most self-hosted apps expect you to drop SMTP credentials into a .env file, then restart the container to pick them up. Stashboard works differently: your Stashboard SMTP email notifications configuration is stored as a single row inside the SQLite database, not in environment variables. This design has two practical benefits.

First, you can change your email server host, port, username, or password through the Notifications UI and the change takes effect on the very next alert — no downtime, no restart. Second, your SMTP password never travels through environment variables, which are visible to anyone who can run docker inspect on the container. If you are new to how Docker handles environment variables and volumes in general, the Docker for beginners post covers the fundamentals well.

Under the hood, every time Stashboard needs to send an email it calls EmailSettingsService.GetResolvedAsync(), which reads the current row from the database and decrypts the password on the fly using AES-256-GCM. The API never returns the plaintext password to the frontend — it exposes only a boolean hasPassword flag so the UI knows whether a credential is already stored.

The environment variables under STASHBOARD_Email__* — for example STASHBOARD_Email__Host or STASHBOARD_Email__Port — act only as a seed: they populate the database row on the very first startup if no row exists yet. After that, the database is the authoritative source, and any change you make in the UI overwrites the seeded values permanently.

Prerequisites

Stashboard is running and you are logged in as an administrator.
You have a Gmail account or another SMTP provider. This guide uses Gmail as the example.
2-Step Verification is enabled on your Google account — Google requires this before you can generate an App Password.

Step 1 — Generate a Gmail App Password

Google blocks your regular account password for SMTP access on accounts with 2-Step Verification active. You need an App Password — a 16-character token that grants SMTP access independently of your main password.

Go to myaccount.google.com/apppasswords.
In the App name field, type Stashboard and click Create.
Copy the 16-character password that appears. Spaces in the display are cosmetic — Gmail ignores them during SMTP authentication.

⚠️ Copy the token immediately. Google shows it only once. If you close the page without saving it you must generate a new App Password — there is no way to retrieve the original value.

Step 2 — Open the Stashboard SMTP Email Notifications Page

In the Stashboard sidebar, navigate to Notifications. The page shows two cards: Email server (SMTP) and Telegram. Click the Email server card to expand the configuration form.

Provider dropdown

The Provider dropdown has two options:

Log only — Stashboard writes email content to the application log instead of delivering anything. Useful for verifying alert rules fire without sending real messages.
Smtp — enables real email delivery via the MailKit SMTP client and reveals the remaining form fields.

Select Smtp to proceed.

SMTP connection fields (Gmail defaults)

Host: smtp.gmail.com
Port: 587
Use StartTLS: checked (enabled)
Username: your full Gmail address, e.g. [email protected]

These match Stashboard’s built-in defaults from appsettings.json, so if your database was seeded from environment variables these fields may already be pre-filled correctly.

The tri-state password field

The password input in the Stashboard SMTP email notifications form behaves differently from a standard password field. It operates in three states:

Keep (default) — Leave the field completely blank. Stashboard sends a null password action to the API. The server preserves the existing AES-256-GCM encrypted value without ever decrypting it. When a password is already stored, the placeholder reads “•••••••• (stored — leave blank to keep)” to confirm this. Use Keep when you are only updating other fields like Host or Port.
Set — Type or paste a new value. The moment you type anything, the field is flagged internally as touched. On save, Stashboard encrypts your new value with AES-256-GCM and writes it to the database, replacing whatever was stored before.
Clear — Available at the API level when you want to remove the stored password entirely, setting the database field to NULL. In practice, switching the Provider back to Log only disables email delivery without needing to clear the credential at all.

Paste the App Password from Step 1 into the password field. Use the eye icon to reveal what you typed and verify it before saving. Paste the 16 characters as-is — no spaces to strip.

Sender identity and App Base URL

From address: the sender address that appears in recipients’ inboxes, e.g. [email protected]
From name: the display name shown in email clients, e.g. Stashboard
App Base URL: the public address of your Stashboard instance, e.g. http://192.168.1.111:8080. Stashboard builds every link inside outgoing emails — account confirmation, password reset, and Docker update alert links — from this value. If Stashboard sits behind a reverse proxy with a domain name, enter your public domain here rather than a LAN IP.

Click Save. The settings take effect immediately — no container restart, no docker compose down.

Step 3 — Test Stashboard SMTP Email Notifications Without Restarting

The quickest way to verify your Stashboard SMTP email notifications work is to trigger a real delivery from the app. The simplest method: log out of Stashboard, click Forgot password on the login page, and enter your account email address. Stashboard will compose and send a password-reset email using the MailKit SMTP client and the settings you just saved — no restart required.

If the email arrives, your Stashboard SMTP email notifications setup is working. If it doesn’t appear within two minutes, run through this checklist:

Check your spam or junk folder first.
Pull the container logs for SMTP errors: docker compose logs --tail=100 app
Verify the App Password is exactly 16 characters with no extra spaces.
Confirm the Provider field is set to Smtp — in Log only mode, output goes to the container log, not your inbox.
Check your Google account for a security alert. App Passwords should bypass “Less secure app” restrictions, but Google occasionally blocks unusual SMTP sessions anyway.

Once basic delivery is confirmed, you can enable Docker image update notifications under Settings → Docker update monitoring. When Stashboard detects a new image digest for a tracked container, it sends a Docker update available email with the container name, current digest, and latest digest. If you manage containers with Portainer, the two tools complement each other well — Portainer gives you the GUI to pull new images, Stashboard tells you when it is time to act.

⚠️ Critical: Back Up the stashboard-data Volume

Your Stashboard SMTP email notifications configuration — including the AES-256-GCM encrypted App Password — lives in the SQLite database inside the stashboard-data Docker volume. The encryption key that makes that password readable is stored at /app/Data/.secrets/encryption.key, also on the same stashboard-data volume. Both the database and the key must be present together for credentials to be decryptable.

⚠️ If you lose the stashboard-data volume you lose the encryption key. Every stored credential — your SMTP App Password, any Telegram bot token, all of it — becomes permanently undecryptable. There is no recovery path.

Back up the volume regularly. The recommended approach from the official Stashboard documentation is to spin up a temporary busybox container that tars the volume contents to your current directory:

# Find the exact volume name on your host (prefixed with the Compose project name)
docker volume ls

# Create a compressed backup archive
docker run --rm \
  -v stashboard_stashboard-data:/data \
  -v "$PWD":/backup \
  busybox tar czf /backup/stashboard-data-backup.tgz -C /data .

Run this with the container stopped for a fully consistent backup, or accept a hot copy for convenience. Store the resulting .tgz file off-host — on your NAS, in cloud storage, or alongside your other Docker volume backups. Pairing this with hardened Docker image practices gives you defence in depth at the container layer as well.

One more scenario to keep in mind: when you migrate Stashboard to a new host, you must bring the full stashboard-data volume with you. Spinning up a fresh instance and importing only the app.db database file — without the .secrets/encryption.key file — will leave all your stored Stashboard SMTP email notifications credentials encrypted with a key that no longer exists. Always transfer the complete volume, not just the database.

Stashboard SMTP Email Notifications Quick-Reference Checklist

✅ Gmail 2-Step Verification enabled and 16-character App Password generated and saved somewhere safe
✅ Notifications → Email server → Provider set to Smtp
✅ Host smtp.gmail.com, Port 587, StartTLS on
✅ Username and App Password filled in; eye icon used to verify before saving
✅ App Base URL points to your real Stashboard address or reverse-proxy domain
✅ Test email received via the Forgot password flow — no container restart needed
✅ stashboard-data volume backed up off-host with encryption key intact

That is everything you need for reliable Stashboard SMTP email notifications in your homelab. The database-backed approach means you can iterate on mail server settings in seconds without touching the container, and AES-256-GCM encryption means your App Password never sits in a plaintext config file. Just make sure that volume backup is scheduled before you forget.

Stashboard is open source — you can find the full source code on GitHub and pull the ready-to-run image directly from Docker Hub. Issues, PRs, and stars are always welcome. 🙌

The Practical Stashboard SMTP Email Notifications Setup Guide