Email and Notifications
GamesDownloader can email you and post to a chat webhook when things happen in your library, and it can watch your instance for suspicious sign-in activity. Everything is configured by an administrator from two places in the admin panel:
- Settings → Notifications holds the shared SMTP server and the webhook (Discord or generic JSON) configuration, including per-event message templates with a live preview.
- Settings → Security holds the email security alerts (per-event toggles) and the periodic security report. Both reuse the SMTP server you set up under Settings → Notifications, so you only enter your mail credentials once.
Most notification settings require an administrator with settings write permission. The one exception is the Security email-alert settings under Settings → Security (read, save, and test), which are open to any signed-in user. See Users & Permissions.
- SMTP server
- Recently added notifications
- Event emails and templates
- Webhook notifications
- Message placeholders
- Email security alerts
- Security report
- Where each setting lives
- Troubleshooting
Settings → Notifications: SMTP server and webhook configuration
Open Settings → Notifications and turn on the SMTP section with the toggle in its header. Fill in your mail provider's details:
| Field | Notes |
|---|---|
| Host | SMTP server hostname, for example smtp.example.com
|
| Port | SMTP submission port, usually 587 for STARTTLS |
| Username | Login for the SMTP account (leave blank for unauthenticated relays) |
| Password | SMTP password; stored encrypted at rest (see below) |
| From address | The From: header, for example noreply@example.com
|
| Test recipient | Where the Send Test Email button delivers to |
| Use TLS | On sends STARTTLS on the given port; off sends without TLS |
When Use TLS is enabled the server negotiates STARTTLS after connecting. With it off, mail is sent over a plain connection. These are the only two modes wired up - the single Use TLS toggle maps to STARTTLS or no TLS. Implicit SSL (connecting over TLS from the start, as some servers expect on port 465) is not selectable in the UI.
Press Send Test Email (visible once a host is entered) to deliver a one-off test message to the test recipient without saving. Then press Save to persist the configuration.
The SMTP password is stored encrypted at rest. It is written to the config store as a secret value, encrypted with the instance key, rather than in plain text. See Configuration for how the encryption key is derived and where config is stored.
When a game or ROM becomes ready in your library - after its metadata is scraped, so the card carries real art - GamesDownloader sends a rich "recently added" notification, one per title, in the style of Plex/Tautulli. It is the flagship, fully working notification and covers the GOG, Games, custom and ROM libraries.
Each Discord card shows the title (linking to the game's page in your library), a short description, a large cover image, a View Details link, a timestamp and a source-coloured bar. Configure it under Settings → Notifications:
- Recently added toggles (one under Webhooks, one under the email server) turn it on per channel. The webhook toggle is on by default; the email one is off (a per-game email can be noisy).
-
Server name is shown in the message -
(MyServer) Title was recently added.- and defaults to the host of your public base URL. -
Advanced templates let you customise the message line, title and body, with the placeholders
{title},{source}and{server}.
You can also (re)send the card by hand from a game's Edit metadata screen (Send notification) - handy after you fix a cover or want to re-announce a title.
Cover images need a reachable URL. Discord fetches embed images from your server, so set Public base URL under Network and Security (e.g.
https://games.example.com) to serve your local covers. Covers from a clean public source (GOG, IGDB, LaunchBox) are shown even without it; ScreenScraper box art is served locally only, because its URLs carry your account credentials and are never sent to a third party.
Configured here, not all delivered. The Recently added email above does send (its own toggle). The separate Download complete, Library sync and Game requests email toggles/templates are saved but not yet sent - groundwork for a planned feature. The other emails that send are the security alerts, the security report, and password-reset messages. For request/sync updates today, use Webhook notifications.
Below the connection fields, Trigger on exposes toggles for three library events - Download complete, Library sync, and Game requests - and Advanced email templates lets you customise a subject and body for each (Download complete, Library sync, the New game request, and each request status: Pending, Approved, Rejected, Done). The body accepts HTML such as <p> and <strong>, and each template has a sanitised live preview that renders sample data as you type. All of it is stored, but nothing consumes these values yet, so no event email is sent.
Webhook message templates with a live preview
The Webhooks section (also under Settings → Notifications) posts a message to an HTTP endpoint when a game request is created, when a request changes status, and when a GOG library sync completes. (Unlike the email settings above, webhooks for these events actually fire.) Enable it with the header toggle, then choose a Webhook type:
| Type | Payload |
|---|---|
| Generic JSON | A plain JSON body: title, message, cover_url, and source
|
| Discord Rich Embed | A Discord webhook payload with a coloured embed: title (optionally a clickable link), description, footer, timestamp, and cover art shown as a thumbnail or - for Recently added - a large image |
Paste the target into Webhook URL (a Discord webhook URL, or your own endpoint for generic JSON), then pick which events fire under Trigger on. Recently added, Library sync and Game requests are emitted; the Download complete toggle has no effect yet (nothing posts that event).
Discord-only options appear when the Discord type is selected:
- Avatar URL overrides the avatar the webhook posts with.
- Include cover art attaches the game cover as the embed thumbnail.
Expand Advanced message templates (shown for the Discord type) to set a custom title and body line for Library sync, the New game request, and each request status (Pending, Approved, Rejected, Done); these are honoured when the webhook fires. A Download complete template is offered as well, but stays unused until that event is emitted. As with email, each template has a live preview rendered with sample data, and a blank template falls back to the default.
Press Send Test (visible once a URL is entered) to post a test notification, then Save.
Discord replies with
204 No Contenton success. If a webhook fails, the test button surfaces the HTTP status and error body so you can see what the remote endpoint rejected.
Generic JSON posts a body like this, which you can parse in your own automation:
{
"title": "New Game Request: Cyberpunk 2077",
"message": "No description provided.",
"cover_url": "https://your-server/media/cover.jpg",
"source": "GamesDownloader"
}The Discord type posts an embeds array with a single embed (title, description, colour, footer, and a thumbnail when a cover is available) and the configured avatar.
Both email and webhook templates substitute the same placeholders. Any that do not apply to a given event are simply left empty.
| Placeholder | Meaning |
|---|---|
{title} |
Game title |
{username} |
User who triggered the event (for requests) |
{status} |
Request status (Pending, Approved, Rejected, Done) |
{platform} |
Library or platform, for example Games or Emulation |
{note} |
Admin note attached to a request |
{description} |
Request description text |
Security alerts are configured under Settings → Security and reuse the SMTP server from Settings → Notifications. Set an alert recipient address; that is where every alert (and the security report) is delivered. Each alert type has its own toggle, all on by default:
| Alert | Sent when |
|---|---|
| Failed login attempts | A wrong password or unknown username is submitted |
| Logins from new IPs | A user signs in successfully from an IP not seen before |
| New user registrations | A new account is created |
| Admin privilege grants | A user is granted administrator rights |
| Brute-force IP bans | An IP is temporarily banned after crossing the failed-login threshold |
Each alert is a self-contained HTML email listing the time (UTC), username, IP address, and client user agent where relevant.
Redis deduplication. To avoid a flood during an attack, alerts are deduplicated per action and IP: at most one email of a given type is sent for a given IP within a 10 minute window. If Redis is unavailable the alert is sent anyway rather than dropped.
Use the test button on the Security alerts panel to send a sample alert through the shared SMTP configuration. If SMTP is not set up, or no alert recipient is configured, the alert system stays silent.
GamesDownloader also sends an automatic notification when an administrator resets another user's two-factor authentication: the affected user is emailed (if they have an address on file) and the alert recipient is notified for the audit trail. This is best-effort and requires SMTP to be enabled.
Also under Settings → Security, the security report is a periodic summary email sent to the alert recipient. Enable it and choose a frequency of Weekly (every 7 days) or Monthly (every 30 days). A background task checks hourly whether a report is due. Enabling the report does not stamp a last-sent time, so the first report can go out on the next hourly check rather than after a full interval; the not-due wait only applies once a report has already been sent.
The report covers the period since the last send and includes:
- Login activity - successful logins, failed logins, blocked attempts, unique active users, and new registrations
- Downloads - number of files downloaded and total data transferred
- Security scans - ClamAV scans completed and threats detected (see ROMs & Emulation and Security for scanning)
- Most active users - the top users by successful logins
Two controls help you check it before relying on the schedule:
- Live preview fetches the current period's statistics and displays them without sending any email.
- Send now delivers the report immediately using the current frequency setting, regardless of when the last one went out.
Both the report and the alerts need a configured SMTP host and an alert recipient. If either is missing, Send now returns an error pointing you back to Settings → Notifications to finish SMTP setup.
| Feature | Tab | Uses Notifications SMTP |
|---|---|---|
| SMTP server | Settings → Notifications | (defines it) |
| Recently added notifications (Discord + optional email) | Settings → Notifications | + (email opt-in) |
| Event emails and templates (configured, not yet sent) | Settings → Notifications | - |
| Webhooks (Discord / generic JSON) | Settings → Notifications | (independent) |
| Email security alerts | Settings → Security | + |
| Security report | Settings → Security | + |
- Test email or alert fails. Confirm the host, port, and TLS mode match your provider. Many providers require an authenticated username and an app-specific password. The error returned by the Test button comes straight from the SMTP server.
- No alerts arrive. Check that SMTP is enabled under Settings → Notifications, that an alert recipient is set under Settings → Security, and that the specific alert toggle is on. Remember alerts are deduplicated per IP for 10 minutes.
- Discord webhook rejected. Verify the webhook URL is a valid Discord webhook and that any avatar or cover URL is reachable. The Test button shows Discord's error response.
- Security report never sends. After a report has gone out, the next one waits for the full weekly or monthly interval; use Send now to verify the configuration immediately.
See Troubleshooting & FAQ for more, and Network & Security for brute-force protection and the audit log that feed these alerts.
Next: Network & Security | Configuration