7 Notifications and Email

TraxrGRC sends plain-text email for reminders, decisions, rule matches, scheduled reports, security alerts and outside assessments. This chapter covers the mail server, the templates every email is built from, the daily sweeps that find due work, notification rules, scheduled report delivery, testing and troubleshooting.

7.1 How email is sent

1. Something in the application decides an email is due: a status change, a daily sweep finding an overdue review, a rule matching, a scheduled report coming round.
2. The application renders the template (subject and body with the placeholders filled in) and writes a row to the delivery log with status Queued.
3. It hands a job to the background worker service through the job queue in the database.
4. The worker connects to the SMTP server from Settings → Integrations and sends the message, then marks the row Sent, or Failed with the server's error.

The consequences for an administrator:

• No worker, no email. The web service only queues. If the worker container is stopped, rows stay Queued until it runs again.
• Links in emails are built from APP_URL. Set it to the address users reach the service at (see Configuration Reference), or every link points to the wrong host.
• Email is plain text, one recipient per message. There are no HTML templates.
• Recipients are accounts, with one exception: assessment emails (assessment.sent, assessment.reminder, assessment.returned) go to the outside contact named on the assessment request. No other email goes to an address that is not a user of this installation, and there are no webhooks.

7.2 Configuring SMTP

The mail server is configured on Settings → Integrations, in the SMTP card. There are no environment variables for it: the settings live in the database and are included in backups. Until it is configured, TraxrGRC tries localhost port 25 with the sender grc@localhost, which fails in a container, so every email is logged as Failed.

Saving and testing are administrator operations.

Rules the server enforces:

• A password is never sent in clear. With a username set and Use TLS off, the server must offer STARTTLS; a relay that does not is refused with an error. Use port 465 with Use TLS, turn on STARTTLS at the relay, or use an unauthenticated relay.
• Changing the host or port clears a stored password unless you type it again in the same save, so a password is never sent to a server it was not entered for.
• An unauthenticated relay is used with opportunistic STARTTLS.

To configure the mail server:

1. Open Settings → Integrations.
2. Fill in the SMTP card and click Save. The save is recorded in the Audit Log with the values before and after (the password only as changed or unchanged), and every administrator is sent a security alert.
3. Click Send test email (see below).

When an instance is restored onto a server with a different settings key, the SMTP password cannot be decrypted: it reads as empty, the server logs settings.decrypt_failed, and authenticated sending fails until you type the password again (see Backup and Restore).

7.3 Testing email

Send test email on the SMTP card sends a message to your own account's address, with the product name and "SMTP test" in the subject. The result appears at once: "Test email sent to your address." or "Test email failed:" with the server's reason.

The test is sent directly by the web service. To prove the whole path through the worker, check a real email in the delivery log:

1. Save the SMTP card. Saving emails every administrator a security alert.
2. Open /settings/notifications, tab Delivery log.
3. Find the security.alert rows for the save. Sent means the worker delivered them; Failed shows the reason in Error; Queued that stays queued means the worker is not running.

For a test instance, the deployment includes a mail catcher that accepts every message and shows it in a web page. It is meant for trying things out, never for production:

docker compose --profile dev up -d mailpit

Then set Host mailpit, Port 1025, no username and Use TLS off, and open http://127.0.0.1:8025 on the server to read the messages.

7.4 The Notifications page

Settings → Notifications (address /settings/notifications) has four tabs:

The built-in GRC Manager role holds read and update on Notifications. All changes are recorded in the Audit Log under the module notifications.

7.5 Templates

Every email TraxrGRC sends is built from a template with a fixed key. The Templates tab lists each one with its Key, Name, Module, Subject and an Enabled switch, with search and column filters. The Module filter offers Risks, Compliance, Policies, Controls, Awareness, Data privacy, Assessments, Reports and Platform.

7.5.1 Template keys and their variables

The variables below are the ones each default template uses. {{app.name}} (the product name from Branding) works in every template.

Dates in reminder variables are written yyyy-MM-dd. alert.time, reset.time and change.time are shown in the recipient's time zone. The digest.daily subject defaults to "{{app.name}} daily digest: {{digest.date}}".

7.5.2 Editing a template

1. Click the template's key. The edit dialog opens.
2. Change the Name (up to 120 characters), Subject (up to 300) or Body. Placeholders are written {{variable.name}}.
3. Check the Available vars panel beside the fields. It lists each variable the template receives, with its meaning, plus app.name.
4. Click Save template. The next email queued from that template uses the new text; emails already queued keep the old text.

Things to know:

• A placeholder the template does not receive renders as nothing; there is no error. Send yourself a test (for example with Run sweeps now on an instance holding test data) after editing.
• There is no "reset to default". Copy the original text somewhere before changing it. The defaults are in prisma/reference-data.ts in the source.
• Upgrades add new templates and never overwrite ones you edited.
• Keep the security wording in notification.rule and report.scheduled that tells people why they receive the email and links to profile.url, where they can opt out.
• Template edits and switches are recorded in the Audit Log with the text before and after.

7.5.3 Turning a template off

The Enabled switch stops a template without editing it. Nothing is sent from a disabled template: fixed notifications are logged as Skipped with the reason template-disabled, and rule and scheduled report emails as Suppressed. Disabling security.alert stops security alerts to administrators; leave it on.

7.6 Scheduler

The Scheduler tab holds the Daily sweeps scheduler card. Once a day the worker scans reviews, exceptions, control tests, awareness programs, data processing agreements, transfer impact assessments and questionnaires and queues the reminders above. The same run handles deadline notification rules, assessment reminders and repeats, and policy acknowledgement reminders.

Click Save settings to store them. Saving applies a changed Cron schedule (UTC) to the job queue at once, and the confirmation reads "Scheduler settings saved. The new schedule is active." If the queue cannot be reached (for example because the worker has never run), the save still succeeds and a warning says "The new schedule takes effect when the background worker next starts"; start or restart the worker in that case:

docker compose restart worker

The digest switch and the lead days apply at the next run.

Run sweeps now runs the whole sweep at once and reports how many items it found, for how many recipients, and how many digests it queued. It sends real email. An item already reminded in the last 20 hours is skipped, so running it next to the scheduled run sends nothing twice. A reminder goes only to a person who can still read the record it names. The run is recorded in the Audit Log.

7.7 Notification rules

Fixed notifications go to record owners on fixed events. Notification rules let an administrator email other people about other events. The Rules tab and every rule action are for administrators only. A new or upgraded installation has no rules.

7.7.1 Creating a rule

1. Click New rule. The New notification rule dialog opens.
2. Fill in the fields and click Create rule (Save rule when editing).

7.7.2 How rules are delivered

• Event triggers (comments, creation, status changes, findings, failed tests) are read from the Audit Log every minute, so an email follows the change within a minute or two.
• Deadline triggers run with the daily sweep, using the scheduler's Review lead days and Exception lead days. A deadline rule emails once when a deadline enters the lead window and once when it passes; moving the date starts again.
• Access is checked twice: when the rule fires and again just before sending. A recipient who may not open the record gets nothing (no-access).
• Nobody is emailed about their own change.
• Each person gets at most 20 rule emails an hour; the rest are suppressed (rate-limit).
• Content is minimal: the record's title or reference, what happened and a link. Comment text, descriptions and other fields are never included. An incident recorded as a personal data breach is named only by a short reference, since its title can name affected people.
• Retries: a rule email that the mail server refuses is tried four times, a minute or more apart, before it is marked Failed. One left in Sending by a crash is marked failed after 15 minutes and never resent.
• Opt-outs: anyone can switch a rule off for themselves on My profile. The Opted out column counts them. An administrator cannot override an opt-out.

7.7.3 Bulk changes and rules

Changes made through an API token (including the bundle loader) and through a CSV import send no rule emails by default; the delivery log lists them as Suppressed with the reason api-write. This keeps a data load from flooding people's inboxes. To include them, turn on Notify on API changes and CSV imports below the rules list. The hourly cap still applies. Fixed notifications (reminders, decisions) are not affected by this switch.

7.8 Scheduled reports delivery

Scheduled reports are set up by users with Reports rights on Reports → Scheduled (see the User Manual, Report Center). For the administrator:

• Each scheduled report email uses the report.scheduled template and is sent through the same SMTP settings and worker. The worker checks for due schedules every minute.
• Each recipient's copy is prepared with that recipient's permissions at sending time, so two people can get different files.
• Files over 10 MB are not attached; the email links to the report instead.
• A schedule missed while the worker was stopped runs once when it comes back.
• Recipients are active users only, and each can unsubscribe on My profile.
• Failed sends are retried like rule emails.
• Administrators see every scheduled report email in the delivery log, with the schedule's name in Rule or schedule and the attachment name.

A new or upgraded installation has no schedules. On an upgraded installation, add Create, Update and Delete on Reports to the roles that should manage schedules (see Users, Groups and Roles).

7.9 The delivery log

The Delivery log tab lists every email, newest first, with Created, Template, To, Rule or schedule, Subject, Status, Error and Sent at. Filter by status and search across the recipient, subject, template key and error. Users who are not administrators do not see rule or scheduled report emails.

A fixed notification that fails is not retried: it stays Failed. Review, exception, control test and awareness reminders come again with the next daily sweep while the item is still due. Reminders sent once per state (data processing agreements, transfer impact assessments and data mapping questionnaires) and event emails such as risk.appetite.breach may not be sent again, so fix the mail server and tell the people concerned.

7.9.1 Troubleshooting

7.10 Deliverability

TraxrGRC hands mail to your SMTP server; whether it reaches inboxes depends on how that server and your domain are set up.

• Send through your organization's relay (Microsoft 365, Google Workspace, or your own mail gateway), never directly to the internet from the server.
• Use a From address on your own domain that the relay may send as, for example a shared mailbox or a send-as permission for [email protected].
• Make sure SPF, DKIM and DMARC cover the relay for that domain. A From address on a domain whose SPF does not list the relay is often rejected or filed as junk, and the delivery log still shows Sent.
• Allow the sender in your mail filtering if reminders land in junk, and tell staff to expect mail from it.
• Assessment emails go to outside contacts. Their mail systems apply their own filtering; a From address on your main domain with DMARC alignment gives the best chance.
• Volume is modest (sweeps once a day, rules capped at 20 per person an hour), but a first sweep after loading a large register can queue many reminders at once. Check the relay's sending limits before go-live.