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
- Who receives what
- Webhook notifications
- Message placeholders
- Email security alerts
- Security report
- Email deliverability (SPF, DKIM, DMARC)
- 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 announces it, Plex/Tautulli style. It is the flagship notification and covers the GOG, Games, custom and ROM libraries. Announcements go out on two independent channels, each with its own switch under Settings → Notifications: a Discord/webhook card (immediate, one per title) and email (immediate per title, or collected into a scheduled digest).
Settings → Notifications: the recently-added email mode, the digest schedule, and the shared Notification recipient
Recently added cards in Discord - one per title, with cover art
The webhook Recently added toggle (under Webhooks, on by default) posts one card per title as soon as it is ready. 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. This channel is always per-item; the digest below applies to email only.
-
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}.
Under the email server, Recently added is a mode selector, not just a switch, so a busy library does not spam every reader:
| Mode | What arrives |
|---|---|
| Off | No recently-added email. (Discord/webhook still fires if enabled.) |
| Immediate | One email per title, the moment it is ready - the same trigger as the Discord card. |
| Daily digest | One newsletter a day, at the time you set, listing everything added since the last one. |
| Weekly digest | One newsletter a week, on the weekday and time you set. |
For Daily and Weekly, choose the Day (weekly only) and Time - the time is your server's local time, shown as Server time beside the field. A background task checks a few times a minute and sends the newsletter once its slot has passed; an "already sent for this slot" guard means nudging the time forward does not re-fire the same day, and a run that fails to deliver leaves its cursor untouched and retries the same window next tick. Send digest now delivers a newsletter immediately (covering at least the last week, reaching further back if the previous send was longer ago) so you can preview the layout without waiting for the schedule.
The digest is a designed HTML email, not a bare cover-and-title list:
The recently-added digest: your logo, a two-per-row grid, and Games / GOG / ROMs sections
- A logo header (
GDLOGO.png) and a "new items" count, in place of a plain From name. - Two cards per row, split into Games, GOG and ROMs sections just like the library.
- Covers keep their natural aspect - portrait box art and landscape ROM art both render without letterboxing.
- Each card carries the title, a short description, the year, a genre chip, a star rating, and a source mark: the GOG icon for GOG titles and the platform wordmark (SNES, Genesis, ...) for ROMs.
- A plain-text version is included beside the HTML for mail clients (and spam filters) that prefer it.
GOG titles inherit their release year and rating from the linked GOG record, so the digest shows the same metadata as everywhere else in the app.
Recipients are resolved per title, at send time: every enabled user who has an email, opted in, and can actually see that item. Per-game access denials and library visibility are respected (a user who cannot open a game is never emailed about it); ROMs follow the emulation-access scope; administrators always qualify. Everyone is BCC'd, so recipients never see each other's addresses.
Each user controls their own opt-in from Profile → Account → Email notifications ("Email me when a game or ROM is added"). It is on by default, and the hint spells out the visibility rule:
Profile → Account: each user's recently-added opt-in (on by default)
The Notification recipient field on the SMTP panel is a catch-all: it is added to the admin-facing mail (library sync, new requests) and to the recently-added send, so a shared inbox can receive a copy even when no individual account is opted in.
You can (re)send a single title's card from its Edit metadata screen with Send notification - handy after you fix a cover or want to re-announce. It posts the Discord/webhook card immediately and, in Immediate email mode, emails it too; in a digest mode the item simply rides the next newsletter. The button is hidden when no channel is set up to deliver an "added" notification.
Send notification (bottom of the metadata editor) re-announces a single title
Cover images need a reachable URL. Discord and remote mail clients fetch cover 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) still show without it; ScreenScraper box art is served locally only, because its URLs carry your account credentials and are never sent to a third party.
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. A blank template falls back to the default.
Two of the three send today; each honours its Trigger-on toggle and goes to the audience it is for (see Who receives what):
| Event | Trigger toggle | Sends to |
|---|---|---|
| GOG Library sync complete | Library sync | Administrators (+ Notification recipient) |
| New game request | Game requests | Administrators (+ Notification recipient) |
| Request status change (Pending / Approved / Rejected / Done) | Game requests | The requester |
| Download complete | Download complete | Groundwork - configured but not yet emitted |
Download complete is groundwork. Its toggle and template are saved, but nothing emits that event yet. The recently-added, request and sync emails above do send, as do the security alerts, the security report, and password-reset mail. For a live download signal today, use a webhook or the Discord card.
Each notification is routed to the audience it is for:
| Notification | Channels | Recipients |
|---|---|---|
| Recently added | Discord/webhook + email | Opted-in users who can see the item (admins always) - BCC |
| GOG library sync | Discord/webhook + email | Administrators + Notification recipient |
| New game request | Discord/webhook + email | Administrators + Notification recipient |
| Request status change | Discord/webhook + email | The requester |
| Security alerts + report | The alert recipient (Settings → Security) |
The Notification recipient (Settings → Notifications) is a shared catch-all folded into the admin-facing and recently-added mail; the alert recipient (Settings → Security) is a separate address that only receives security mail. Every multi-recipient email is sent as one BCC message, so addresses are never disclosed to other recipients.
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 - the same events the event emails cover, on an independent channel. 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 |
Settings → Security: email alerts reuse the SMTP server configured under Settings → Notifications
Security alerts are configured under Settings → Security and reuse the SMTP server from Settings → Notifications ("SMTP server is shared with Notifications. Configure it there first."). 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.
Getting mail accepted is separate from sending it. GamesDownloader stamps each message with a proper Date and a unique Message-ID, delivers multi-recipient mail as a single BCC message (sending the same mail as several separate copies makes relays and Gmail collapse them into one, so only the first recipient would receive it), and includes a plain-text part beside the HTML. The rest is DNS on the domain in your From address:
| Record | Why it matters |
|---|---|
| SPF | Authorises your SMTP relay to send as your domain. |
| DKIM | Signs the message so the receiver can verify it was not tampered with. Usually enabled at your mail provider. |
| DMARC | Ties SPF and DKIM together and tells receivers what to do. Even a permissive _dmarc.<domain> TXT record of v=DMARC1; p=none is often the difference between Gmail placing your mail in the inbox and dropping it silently. |
If a test email arrives but real notifications do not - especially at Gmail - a missing DMARC record is the usual cause, even when SPF and DKIM are already in place. Your provider's dashboard will show whether messages were delivered; check that and your DNS for the three records above.
| Feature | Tab | Uses Notifications SMTP |
|---|---|---|
| SMTP server | Settings → Notifications | (defines it) |
| Recently added email (off / immediate / daily / weekly digest) | Settings → Notifications | + |
| Per-user recently-added opt-in | Profile → Account | + |
| Event emails - Library sync, Game requests (Download complete is groundwork) | 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.
- Recently-added email never arrives. Check the Recently added mode under Settings → Notifications is not Off, and (for a normal account) that Profile → Account → Email notifications is ticked. In a digest mode, mail only goes out at the scheduled slot - use Send digest now to send immediately. If a test email works but notifications do not, see Email deliverability.
- Only one recipient gets a multi-recipient email. GamesDownloader sends one BCC message rather than separate copies, so this should not happen; if it does, a mail relay collapsing look-alike messages is the classic cause. Confirm your From domain has SPF, DKIM and especially DMARC (see Email deliverability).
- 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