Email and Notifications

Email & 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.

All notification settings require an administrator with settings write permission. See Users & Permissions.

Contents

• SMTP server
• Event emails and templates
• Webhook notifications
• Message placeholders
• Email security alerts
• Security report
• Where each setting lives
• Troubleshooting

SMTP server

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	Usually 587 for STARTTLS or 465 for implicit SSL
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. Implicit SSL on port 465 is also supported by the underlying sender.

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.

Event emails and templates

Below the connection fields, Trigger on lets you choose which library events send an email. All three default to on:

Event	Fires when
Download complete	A download finishes and is ready to play
Library sync	A GOG library synchronisation completes
Game requests	A game request is created or changes status

Expand Advanced email templates to customise the subject and body of each mail. The body accepts HTML, so you can use simple formatting such as <p> and <strong>. Templates exist for Download complete, Library sync, the New game request, and each game-request status: Pending, Approved, Rejected, and Done. Leaving a template blank uses the built-in default shown as the placeholder.

Each template has a live preview that renders your subject and body with sample data as you type. The preview HTML is sanitised, so any scripts or event handlers you paste are stripped from the rendered preview.

Webhook notifications

The Webhooks section (also under Settings → Notifications) posts a message to an HTTP endpoint on the same three events. 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 (Download complete, Library sync, Game requests).

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 Download complete, Library sync, New game request, and each request status (Pending, Approved, Rejected, Done). 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 Content on success. If a webhook fails, the test button surfaces the HTTP status and error body so you can see what the remote endpoint rejected.

Payload shapes

Generic JSON posts a body like this, which you can parse in your own automation:

{
  "title": "Download Complete: Cyberpunk 2077",
  "message": "Cyberpunk 2077 has finished downloading.",
  "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.

Message placeholders

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

Email security alerts

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.

Security report

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, so the first report arrives after the interval has elapsed.

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.

Where each setting lives

Feature	Tab	Uses Notifications SMTP
SMTP server	Settings → Notifications	(defines it)
Event emails and templates	Settings → Notifications	+
Webhooks (Discord / generic JSON)	Settings → Notifications	(independent)
Email security alerts	Settings → Security	+
Security report	Settings → Security	+

Troubleshooting

• 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. It sends only after a 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