07.02 Email and the Notification Extra

Requires: Notification Extra

Per-event notifications, the email queue, the notification cron, and the per-event recipient logic all live in the Notification Extra at simplerisk/extras/notification/. The SMTP server connection itself (the PHPMailer settings) is configured in Core. Without the Notification Extra activated, only Core's auth-related emails (password reset, MFA reset confirmation) get sent; risk and compliance event notifications don't.

Why this matters

Email is how SimpleRisk reaches the user outside the application. A user who's not logged in still gets the "your risk is pending review" email; a stakeholder who never logs in still receives the executive summary their team configured. For most programs, email is the primary channel for keeping the broader stakeholder population engaged with the GRC program. Without email, the program's reach contracts to "people who actively log in regularly" — a much smaller set than "people who care about the program's findings."

The configuration has two layers: SMTP connection (Core, configured under Mail Settings) and per-event notifications (Notification Extra, configured under the Notification admin page). Both have to work for SimpleRisk to send emails for risk events. Many "email isn't sending" troubleshooting sessions trace to one of these layers being misconfigured.

The honest scope to know up front: SMTP configuration is a one-time setup that's hard to get right. Modern email delivery requires not just SMTP credentials but also sender domain configuration (SPF, DKIM, DMARC), reputation warming, and provider-specific quirks. A misconfigured sender produces emails that land in spam, get rejected, or get delivered with broken headers. The configuration in SimpleRisk is the easy part; the deliverability work is the hard part.

The other thing worth knowing: email sends asynchronously via the notification cron, not synchronously on the user's action. When a user submits a risk, the notification doesn't block the user's submission; the event queues into notification_sent_log (or equivalent), and the next cron tick (cron_notification.php) sends the queued emails in batch. This decouples application performance from SMTP latency but means email delivery has a few-minute lag depending on the cron frequency.

The third thing: the per-event toggles control who gets what. SimpleRisk has nine event types (new risk, risk update, mitigation, review, close, comment, audit initiate, audit comment, audit status change) and per-event recipient logic (notify the submitter, the owner, the manager, the team, etc.). Tuning these toggles is how you keep the email volume tractable; defaulting everything to "notify everyone" produces alert fatigue.

Before you start

Have these in hand:

Admin access to Configure → Settings → Mail Settings (for SMTP) and Configure → Notification (for the per-event toggles).
SMTP credentials for an email service. Production-grade options:
Cloud transactional email service: SendGrid, Mailgun, AWS SES, Postmark — all reliable, support proper sender authentication, scale to high volume.
Office 365 / Google Workspace SMTP: works for low-to-moderate volume; subject to anti-abuse rate limits at high volume.
On-prem SMTP server (corporate Exchange, Postfix, etc.): works inside the corporate network; may require allowlisting SimpleRisk's IP.
A sender email address. Often simplerisk@your-domain.com or noreply@your-domain.com. The address must be authorized to send on behalf of your domain (SPF/DKIM/DMARC) — talk to your email administrator if you're not sure.
An understanding of the email volume. A 50-user install with daily risk activity produces a few hundred emails per day; a 500-user install with active workflows can produce thousands. Pick an SMTP service tier that handles your volume.
A test inbox you control (not a shared address) for the test-email verification step.

Step-by-step

1. Activate the Notification Extra

Sidebar: Configure → Extras → Notification Extra → Activate. The activation:

Initializes the NOTIFY_ON_* settings for nine event types.
Creates the cron_history and notification_sent_log tables.
Surfaces the Notification admin page where per-event toggles and email templates are configured.

If the Extra is already active, skip.

2. Configure the SMTP connection (Core Mail Settings)

Sidebar: Configure → Settings → Mail Settings (the page lives in simplerisk/admin/index.php or equivalent). The fields:

Transport (phpmailer_transport) — smtp for any production SMTP service. sendmail only for installs where the local server's sendmail binary is configured (rare in modern deployments).
Host (phpmailer_host) — the SMTP server hostname (e.g., smtp.sendgrid.net, smtp.mailgun.org, smtp.office365.com, email-smtp.us-east-1.amazonaws.com).
Port (phpmailer_port) — typically 587 for STARTTLS, 465 for implicit TLS, 25 for unencrypted (don't use 25 in production).
Encryption (phpmailer_encryption) — tls for STARTTLS (port 587), ssl for implicit TLS (port 465), none for unencrypted.
Authentication required (phpmailer_auth) — true for any production SMTP service.
Username (phpmailer_username) — the SMTP authentication username (varies by service: API key for SendGrid, full email for Office 365, etc.).
Password (phpmailer_password) — the SMTP authentication password / API secret. Stored encrypted.
From Email Address (mail_from) — the sender address that appears on outgoing emails.
From Name — the friendly sender name (e.g., "SimpleRisk Notifications").

Save the configuration. SimpleRisk uses PHPMailer (a Composer dependency) to handle the SMTP transaction.

3. Send a test email

The Mail Settings page exposes a Send Test Email button. Click it:

SimpleRisk sends a test email to the currently logged-in user's email address.
Confirmation appears in the UI ("Test email sent" or an error message).
Check your inbox; the test email should arrive within a minute (often within seconds).

The test is rate-limited to 5 attempts per hour to prevent accidentally hammering the SMTP service during configuration debugging. If you exceed the limit, wait an hour or unwind the rate limit in the database.

If the test fails:

Authentication failure: double-check the username and password / API key.
Connection refused / timeout: verify the host and port are reachable from the SimpleRisk server (firewalls often block outbound 25/465/587 to public hosts).
TLS / SSL error: verify the encryption setting matches the port (TLS for 587, SSL for 465).
Sender address rejected: the configured mail_from may not be authorized for the SMTP service or your domain. Check SPF/DKIM/DMARC.

If the test succeeds but the email lands in spam, the issue is sender reputation / authentication, not SimpleRisk-side configuration. Talk to your email administrator about SPF, DKIM, and DMARC records.

4. Configure per-event notification toggles

Sidebar: Configure → Notification. The page lists the nine events with per-event recipient toggles:

New Risk (NOTIFY_ON_NEW_RISK) — fires when a risk is submitted.
Risk Update (NOTIFY_ON_RISK_UPDATE) — fires when a risk is edited.
New Mitigation (NOTIFY_ON_NEW_MITIGATION) — fires when a mitigation is added.
Mitigation Update (NOTIFY_ON_MITIGATION_UPDATE) — fires when a mitigation is edited.
Risk Review (NOTIFY_ON_RISK_REVIEW) — fires when a risk is reviewed.
Risk Close (NOTIFY_ON_RISK_CLOSE) — fires when a risk is closed.
Risk Comment (NOTIFY_ON_RISK_COMMENT) — fires when a comment is added to a risk.
Audit Initiate (NOTIFY_ON_AUDIT_INITIATE) — fires when an audit cycle starts.
Audit Comment (NOTIFY_ON_AUDIT_COMMENT) — fires when a comment is added to an audit.
Audit Status Change (NOTIFY_ON_AUDIT_STATUS_CHANGE) — fires when an audit's status changes.

For each event, configure recipient toggles (typical options: notify the submitter, the owner, the owner's manager, the team, additional stakeholders). Save.

Tune for noise: a default "notify everyone on every event" produces alert fatigue and discount-from-overuse. Start with focused notifications (notify the assigned owner on actions that affect them) and expand as the program's communication needs become clearer.

5. Customize the email templates

The Notification Extra also manages email templates (subject and body for each event). See Customizing Email Templates for the template-editing workflow. The default templates work; the customized ones are better.

6. Confirm the notification cron is running

Email is sent asynchronously. The notification cron (simplerisk/cron/cron_notification.php) needs to run for emails to actually send. Verify:

Check the cron schedule (typically every few minutes; configured under Configure → Settings → Backups in the cron settings, despite the page name). The cron is run by the same scheduler as the rest of SimpleRisk's cron jobs.
Submit a test risk; wait for the next cron tick.
Check whether the queued notification was sent (the notification_sent_log table records sent emails).

If the cron isn't running, queued notifications accumulate without sending. See The Cron Jobs for the cron-system overview.

7. Plan for sender reputation

For new SimpleRisk installs sending from a fresh sender domain or IP:

Warm up the sender: SMTP services and major receivers (Gmail, Outlook) treat a brand-new sender with suspicion. Send low volume initially (a few emails per day) and ramp up over weeks.
Monitor deliverability: watch your SMTP service's bounce and spam-complaint metrics. High rates mean reputation issues.
Configure SPF, DKIM, DMARC for your sending domain. Without them, modern receivers reject or spam-flag your mail. Most SMTP services have setup guides specific to their service.

8. Plan for high-volume scenarios

For installs with high notification volume:

Choose an SMTP service tier that handles your peak rate.
Tune notification toggles to suppress noise.
Monitor the notification queue (notification_sent_log row count growth) to catch backlog before it impacts delivery latency.
Coordinate with the email administrator if your sender domain is shared with other sources of mail (avoid one sending pattern hurting another's reputation).

Common pitfalls

A handful of patterns recur with email and notifications.

Configuring SMTP and never sending the test email. "It's saved, so it must work." Send the test; verify delivery; iterate until it works.
Test email landing in spam. This is sender reputation / authentication, not SimpleRisk. Talk to your email administrator about SPF/DKIM/DMARC; consider switching to a transactional email service.
Using cleartext SMTP (port 25, no encryption) in production. Credentials transmit in clear; modern SMTP services don't even allow this. Use 587/STARTTLS or 465/SSL.
Activating notifications without configuring SMTP. Notifications queue but can't send; the queue grows; nothing happens. Configure SMTP first.
Overriding the from-address for individual notifications. Don't. The configured mail_from is what your domain is authorized to send from; per-notification overrides typically fail authentication.
Notifying everyone on everything. Alert fatigue is a deliverability problem too — emails marked as "junk" by recipients hurt sender reputation. Tune the toggles.
Forgetting that the notification cron has to run. Queued notifications accumulate without the cron. See The Cron Jobs.
Storing the SMTP password in cleartext outside SimpleRisk. SimpleRisk encrypts the stored password; don't leak it elsewhere.
Running multiple SimpleRisk instances against the same SMTP credentials. Rate limits and reputation impact accumulate across both. Use separate credentials per environment (production vs staging vs dev).
Not coordinating SMTP changes with the email administrator. Switching from on-prem to a cloud SMTP service or vice versa changes the sender's IP and authentication; the email admin needs to update SPF/DKIM/DMARC accordingly. Coordinate the change.
Treating Office 365 SMTP as a high-volume option. Microsoft's SMTP relay has rate limits (typically 10,000 messages per day); high-volume installs need a proper transactional email service.
Not accounting for the test-email rate limit. 5 tests per hour; if you're iterating configuration changes rapidly, the limit kicks in. Pace your testing or unwind the rate limit explicitly during debugging.

Customizing Email Templates
The Jira Extra
Webhook Integration
Using the API for Integrations
The Cron Jobs
Local Authentication and Password Policies (for password-reset emails)

Reference

Permission required: check_admin for Mail Settings and the Notification admin page.
API endpoint(s): None specific to email configuration; POST /api/v2/admin/test_email (or equivalent) triggers the test send.
Implementing files: simplerisk/includes/mail.php (get_mail_settings(), update_mail_settings(), the PHPMailer wrapper); simplerisk/extras/notification/index.php (the per-event notification triggers, the recipient logic, the queue management); simplerisk/cron/cron_notification.php (run_notification_crons() — the asynchronous send loop).
Database tables: notification_sent_log (record of sent notifications, used for deduplication and audit); cron_history (cron-run records).
config_settings keys: notification (Notification Extra activation); phpmailer_transport, phpmailer_host, phpmailer_port, phpmailer_encryption, phpmailer_auth, phpmailer_username, phpmailer_password (encrypted), mail_from (Core SMTP settings); NOTIFY_ON_NEW_RISK, NOTIFY_ON_RISK_UPDATE, NOTIFY_ON_NEW_MITIGATION, NOTIFY_ON_MITIGATION_UPDATE, NOTIFY_ON_RISK_REVIEW, NOTIFY_ON_RISK_CLOSE, NOTIFY_ON_RISK_COMMENT, NOTIFY_ON_AUDIT_INITIATE, NOTIFY_ON_AUDIT_COMMENT, NOTIFY_ON_AUDIT_STATUS_CHANGE (per-event recipient toggles).
External dependencies: A reachable SMTP server / service; appropriate sender-domain authentication (SPF, DKIM, DMARC) for production deliverability; PHPMailer (bundled).