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
- 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.
Configured here, not yet delivered. GamesDownloader saves these toggles and templates, but no code currently sends event emails for downloads, library syncs, or game requests - the settings are groundwork for a planned feature. The emails that actually send are the security alerts, the security report, and password-reset messages, all covered below. To get notified about new requests or GOG syncs today, use Webhook notifications instead.
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, description, footer, and optional cover thumbnail |
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. Toggles are shown for Download complete, Library sync, and Game requests, but only Library sync and Game requests are actually emitted - nothing posts the Download complete event yet, so its toggle currently has no effect.
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) |
| 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