System Emails — Branded Template System
Feature Overview
Every transactional email PPP sends (welcome, password reset, CPD approval, timesheet approval, hospital invite, 360 review, etc.) must render through a single shared shell so that branding, accessibility, and copy conventions are consistent and maintainable.
The timesheet approval email shows each entry's duration net of the meal break, with the break beside it ("3:30 (30m break)"), and labels the total "Total Duration (after meal breaks)" (Rob, 5 Oct 2026, #12936; flagged for Matt). The branded shell and layout are unchanged.
This spec is the single source of truth for: brand tokens, the shell contract, the email inventory, copy guidelines, and the asset-hosting decision.
Open Questions
| # | Question | Ref | Proposed answer |
|---|---|---|---|
| 1 | Matt did not give an exact target size for the header logo — only "bigger than the AMC badge". Is full-native 360×120 the right dominant scale, or larger/smaller? | #7853 | Adopted 360×120 (the asset's full native 3:1 size) — renders at full resolution without upscaling blur and is clearly larger than the ~140px accreditation badge. Awaiting Matt's eyes-on sign-off. |
Source
- Rob & Matt call 13 Apr 2026 — Matt's #4569 report flagged the welcome email had no logo and used "CPD Dashboard" copy for full-platform users
- Inventory audit of
api/backend-ppp/src/services/**+api/backend-ppp/src/utils/email-templates.tson 2026-04-13
Architecture
Module layout
api/backend-ppp/src/utils/email/
├── branding.ts # Brand tokens: colors, fonts, company name, asset URLs
├── shell.ts # renderBrandedEmail({...})
├── components.ts # button(), infoBox(), kvTable(), divider(), fallbackLink(), paragraph()
├── templates/ # one file per email flow
│ ├── welcome.ts
│ ├── pending-account.ts
│ ├── password-reset.ts
│ ├── cpd-approval.ts
│ ├── timesheet-batch-approval.ts
│ ├── timesheet-payroll-approved.ts
│ ├── timesheet-admin-officer-forwarded.ts
│ ├── ppp360-review.ts
│ ├── hospital-invite.ts
│ ├── registration-link.ts
│ ├── cpd-plan-submission-reminder.ts
│ ├── cpd-activity-created.ts
│ ├── appraisal-notification.ts
│ ├── support-faq-question.ts
│ ├── support-faq-answer.ts
│ ├── roster-management.ts
│ └── gmc-validation.ts
└── index.ts # barrel exportShell contract
renderBrandedEmail({
preheader: string, // hidden inbox-preview line (max 110 chars)
heading: string, // main H1 below the logo
intro: string, // opening paragraph(s) — "Hi {name},\n\n..."
body: string, // pre-rendered HTML from component helpers
cta?: {
label: string, // button text
url: string, // absolute HTTPS URL
},
fallbackUrl?: string, // if present, auto-wrapped with copy-link instruction
footer?: string, // defaults to © Professional Performance Portfolio + support link + Privacy Policy / Terms links (#8322)
}): stringRules enforced by the shell:
- All user-supplied strings must be HTML-escaped by the shell, not callers
- Table-based layout (Outlook-safe) with inline styles only (no
<style>blocks, no CSS classes) - Mobile viewport
<meta>+ responsive max-width 600px - Preheader hidden via zero-height
<div>withdisplay:none+ CSS hack - All links get
target="_blank" rel="noreferrer" - Logo uses PNG (not SVG — Gmail/Outlook SVG support is flaky)
- Logo is embedded inline by Content-ID (
<img src="cid:ppp-logo-email">), NOT a remote URL — image-blocking clients (Apple Mail/Outlook) render inline attachments without the recipient trusting the sender (#8403). The alt text carries brand-styled inline typography as the all-images-off fallback.
Brand tokens (branding.ts)
export const BRAND = {
companyName: 'Professional Performance Portfolio',
primary: '#117BE5', // PPP brand blue (CTA bg) — COLORS.ppp.primary, not the off-brand Tailwind #2563eb (#8319)
darkBlue: '#003977', // PPP dark navy (COLORS.ppp.darkBlue) — headings/anchors
primaryText: '#ffffff',
textPrimary: '#1f2937',
textMuted: '#6b7280',
border: '#e5e7eb',
panelBg: '#f9fafb',
fontStack: "'Helvetica Neue', Arial, sans-serif",
logoUrl: `${process.env.EMAIL_ASSET_BASE_URL}/ppp-logo-email.png`,
emblemUrl: `${process.env.EMAIL_ASSET_BASE_URL}/ppp-emblem-email.png`,
supportEmail: 'support@professionalperformanceportfolio.com',
// Public marketing pages linked from every email footer for compliance (#8322)
marketingBaseUrl: 'https://professionalperformanceportfolio.com',
privacyPath: '/privacy-policy',
termsPath: '/terms',
};Asset hosting
Decision: Cloudflare Pages, served from the managed web-app host — WEB_APP_BASE_URL (ppp-uat. in UAT, ppp. in prod). The earlier app.professionalperformanceportfolio.com host is a dead orphan (not in the Pulumi subdomains map; serves Cloudflare Error 1000) and must NOT be used — see #8320 / #8358 / #8360.
All transactional email links and the medical-passport share URL are built from getWebAppBaseUrl() (WEB_APP_BASE_URL), never the literal app. host (#8360).
- Canonical PNGs live in
instances/ppp/public/email-assets/ppp-logo-email.png— 360×120 @ 2x (720×240 native) for retina sharpness (#9821)ppp-emblem-email.png— 120×120 @ 2x (240×240 native)ppp-provider-badge-light.png— 720px wide, use on white/light-grey backgrounds (#6167)ppp-provider-badge-dark.png— 720px wide, use on navy/dark-hero backgrounds (#6167)
Provider accreditation badge (EMAIL_ASSETS.providerBadgeLight / providerBadgeDark): PPP's own mark for vetted external content providers. Two variants (light/dark) replace the earlier amcBadge slot. Both are gated behind EMAIL_AMC_BADGE_ENABLED env var — emails degrade to a text-only verification link until the flag is enabled (#6167).
_headersrule setsCache-Control: public, max-age=31536000, immutableon/email-assets/*EMAIL_ASSET_BASE_URLresolves to the managed host's/email-assetspath —https://ppp-uat.professionalperformanceportfolio.com/email-assets(UAT) etc. Since #8403 the header logo no longer uses this — it is embedded inline (see below);EMAIL_ASSET_BASE_URLnow only serves the optional provider-accreditation badge. For the deployed backend it is injected by the Azure Pulumi stack (api/infra-azure/src/index.ts, derived from the same host asWEB_APP_BASE_URL). The Dopplerppp/*configs (used for local dev) also carry it. The earlier intent of pointing it at the deadapp.host is retired (#8360)- The existing
PPP_LOGO_URLenv var andGOOGLE_DRIVE_FALLBACKconstant are deleted in child #4944
Header logo: inline (CID) embedding (#8403)
Matt's "no logo in the email" reports (#8319, #8322) were not an asset bug — ppp-logo-email.png serves 200 image/png from the public host. They were client-side remote-image blocking: Apple Mail and Outlook suppress a remote <img src="https://…"> until the sender is trusted. No code can force a remote image to display everywhere.
The header logo is therefore embedded as an inline (CID) attachment rather than fetched remotely:
- The logo PNG is bundled into the backend as a base64 constant (
logo-asset.generated.ts, regenerated bypnpm --filter @ppp-org/backend-ppp gen:email-logo; a sync-guard test fails on drift). No runtime file or network dependency — it can't dead-end the way theapp.host did (#8320). - The shell renders
<img src="cid:ppp-logo-email">(shell.ts renderLogo).mailer-helper.ts sendEmailauto-attaches the bytes as an inline attachment (ACSEmailAttachment.contentId) whenever the HTML references that cid — so no caller changes. - Inline attachments are part of the MIME message, so image-blocking clients render the logo without the recipient trusting the sender. Gmail already auto-displays images for our authenticated sender.
- All-images-off fallback: the
alttext carries brand-styled inline typography (darkBlue, bold) so the header still reads as the company name when every image is suppressed. - Limitation: this is not BIMI. The verified-sender avatar (Gmail/Apple list view) requires a VMC + registered trademark + ~US$1k/yr — explicitly not pursued (#8403 decision).
Deliverability / sender authentication
The domain passes SPF, DKIM, and DMARC, so reputable clients (notably Gmail) auto-display remote images and inbox placement is strong. Confirmed live (professionalperformanceportfolio.com):
- SPF —
v=spf1 include:_spf.google.com include:sendgrid.net include:spf.protection.outlook.com -all. Thespf.protection.outlook.cominclude covers the Azure Communication Services (ACS) send path; Google Workspace and SendGrid are also authorised; hard-fail-all(#4397). - DKIM — Google Workspace key + two SendGrid keys; ACS signs with its own aligned DKIM, so DMARC passes on every send path.
- DMARC —
v=DMARC1; p=quarantine; pct=100(staged enforcement towardp=reject, #2918).
All three records are managed in Pulumi (api/infra-cloudflare/src/dns-records.ts).
Why Cloudflare Pages, not a new CDN subdomain:
- We already serve
instances/ppp/public/at the PPP domain - No new infrastructure, no new DNS record, no new Pulumi module
- Same edge cache as the app
- Single point of invalidation when we rebrand
Why PNG, not SVG:
- Outlook (all versions) has inconsistent SVG rendering
- Some Gmail clients strip SVG as a security measure
- PNG is universally rendered and @2x files are small (<40 KB each)
Email inventory
| # | Flow | Trigger | Current location | Migrated in |
|---|---|---|---|---|
| 1 | Welcome (full account) | authService.signUp | authService/index.ts (inline) | #4943 |
| 2 | Pending account | authService.signUp when hospital_staff | authService/index.ts (inline) | #4943 |
| 3 | Password reset | Better Auth callback | email-templates.ts | #4944 |
| 4 | CPD approval | cpdUserActivities.approveCpdActivity | email/templates/cpd-approval.ts | #5762 |
| 5 | Timesheet batch approval | timesheetBatchWorkflow | email-templates.ts | #4944 |
| 6 | Payroll admin timesheet approved | timesheetPayroll | email-templates.ts | #4944 |
| 7 | Admin officer timesheet forwarded | timesheetBatchWorkflow | email-templates.ts | #4944 |
| 8 | 360 reviewer | ppp360Service | email-templates.ts | #4944 |
| 9 | Registration link | sendRegistrationLink | authService/sendRegistrationLink.ts (inline) | #4945 |
| 10 | Hospital invite | hospitalInviteService | hospitalInviteService/index.ts (inline) | #4945 |
| 11 | CPD plan submission reminder | cpdPlanService/notification | submissionReminder.ts (inline) | #4946 |
| 12 | CPD activity created | cpdUserActivities.emailOnCreate | cpdUserActivities/index.ts (inline) | #4946 |
| 13 | Appraisal notification | scheduledNotificationService | processAppraisalNotifications.ts (inline) | #4946 |
| 14 | Support FAQ question | supportServices.faqQuestion | supportServices/faqQuestion.ts (inline) | #4947 |
| 15 | Support FAQ answer | supportServices.faqAnswer | supportServices/faqAnswer.ts (inline) | #4947 |
| 16 | Roster management | hospitalAdminRosterService | rosterManagement.ts (inline) | #4947 |
| 17 | GMC validation notice | gmcRegistrantService | fetchGmcRegistrantDirect.ts (inline, audit) | #4947 |
| 18 | Logbook case pending review | activitiesService.notifyAssessorOnLogbookSubmission | email/templates/logbook-assessor.ts | #9189 |
| 19 | Membership renewal notice | renewalNoticeService.handleUpcomingInvoice | email/templates/subscription-renewal-notice.ts | #11017 |
| 20 | Compliance form (exemption/variation/internal review/formal review/appeal) member acknowledgement | complianceFormService.submitComplianceForm | email/templates/compliance-form-acknowledgement.ts | #11049, #11048, #11050 |
| 21 | Compliance form (exemption/variation/internal review/formal review/appeal) member outcome | complianceFormService.notifyComplianceFormDecision | email/templates/compliance-form-outcome.ts | #11049, #11048, #11050 |
Note on #20/#21: both are member-facing, distinct from the pre-existing internal exemptions@/appeals@ staff-mailbox notification (compliance-form.ts). #21's caller (notifyComplianceFormDecision) is wired up as of #11048, invoked from the super-admin decide procedure's decision-recording path — no longer a separate, un-integrated tracking item.
#11050 widened all three compliance templates (#20, #21, and the internal staff-mailbox notification) from exemption | variation | appeal to also carry internal_review and formal_review, so the two review tiers Review and Appeal § Part A.2 defines get correctly-labelled acknowledgement and outcome emails rather than falling back to appeal wording. The internal notification also has a conditional recipient for the first time: a cultural-grounds exemption/variation routes to the Cultural Advisor mailbox instead of exemptions@, and its subject is prefixed Cultural Advisor referral —, which is the platform-side precondition for Granting Exemptions § 3's guarantee that no such request is assessed without Cultural Advisor input. Every other route is unchanged.
Note on #19: this is the only email in the inventory whose existence is a published external commitment — PPP's operational policy, shown to the AMC, states that subscribed users are emailed 2 weeks before the annual membership charge. It is sent from the Stripe invoice.upcoming webhook, is idempotent per (subscription, billing period), and does not fire until renewals are issued as Stripe Subscriptions. See docs/site/integrations/stripe.md § 5.1.
Copy guidelines
Vocabulary
| Use | Not |
|---|---|
| sign in | log in / login |
| sign up | register (when referring to creating an account; "regulatory registration" is distinct) |
| Professional Performance Portfolio | PPP (except in casual body copy after first mention) |
CTA patterns
- Primary CTA label should name the destination, not the action:
Go to your Professional Performance PortfoliobeatsClick here - For approval emails:
Review & approve timesheet/Review CPD activity/Provide 360 review - Always pair the button with a fallback link wrapped in: "Or, copy this link to your browser to sign in:" (or equivalent verb)
Preheader
First 110 characters the inbox shows next to the subject line. Must add value beyond the subject — never repeat it.
Good: Subject: Your PPP account credentials / Preheader: Your temporary password is inside. Sign in and change it on first visit.
Bad: Subject: Your PPP account credentials / Preheader: Your PPP account credentials are ready
Acceptance Criteria (epic-level)
- ✅
email.branding.header-logo-size— the PPP logo in the email shell renders at a visual scale comparable to professional body emails (e.g. AMC); the PPP logo must be the dominant branded element at the top of the email, not smaller than equivalent elements in competitor or partner communications.† (#7316, #7853 — rendered at full native 360×120 so PPP dominates the AMC badge) - ✅
email.branding.logo-displays-reliably— the header logo displays in image-blocking clients without the recipient trusting the sender, by embedding it inline by Content-ID rather than a remote URL; with all images disabled the header still reads as the company name in brand colour.† (#8403, closes #8319/#8322 — supersedes the BIMI-framed criteria; BIMI/VMC explicitly not pursued) - ✅
email.deliverability.spf-acs-coverage— SPF authorises the ACS send path (include:spf.protection.outlook.com) alongside Google and SendGrid, DKIM aligns on every path, and DMARC is enforced; documented in this spec.† (#8403) - ✅
email.template.logbook-assessor— submitting a surgical logbook case for sign-off sends a branded "Logbook Case Pending Your Review" email to the responsible consultant through the shared shell (a newemail/templates/logbook-assessor.tsflow), mirroring the WBA assessor email. Delivery is best-effort and never blocks the submit. Behaviour and the assessor-routing semantics are specified inlogbook.md(logbook.review.assessor-email-on-submit).† (#9189) - ⏳
email/module exists with shell + components + branding + templates/ - ⏳ Every email listed in the inventory above is migrated to
email/templates/ - ⏳ No inline
<div style="font-family:strings remain in service files - ⏳
PPP_LOGO_URLandGOOGLE_DRIVE_FALLBACKare deleted - ⏳
email-shell-gateCI gate (.github/scripts/check-email-shell.mjs) prevents net-new raw-HTML email rendering paths from landing; allowlist drains to empty as legacy senders migrate (#5766) - ⏳ Cloudflare Pages serves
/email-assets/*with immutable cache - ⏳
EMAIL_ASSET_BASE_URLset in Doppler uat + prod - ⏳
system-emails.featurehas one@smokescenario per child issue - ✅ Dev preview route lists every template
What NOT To Do
- ❌ Switch to React Email / MJML — plain template strings + shell is the contract
- ❌ Inline SVG logos — use PNG
- ❌ Send new emails without adding a template file to
email/templates/ - ❌ Copy-paste the shell HTML into a new template — always go through
renderBrandedEmail() - ❌ Use CSS classes or
<style>blocks — inline styles only (email clients)
Open issues on label:feature:system-emails — issue data unavailable at build time.Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-10-05 | The timesheet approval email shows each entry duration net of the meal break with the break beside it ("3:30 (30m break)") and labels the total "Total Duration (after meal breaks)". Template layout and branded shell are unchanged. | #0, #11181, #12936 | Rob 5 Oct 2026 Task 3 recording review: displayed hours are net of the meal break (06:00-10:00 with a 30 minute break reads 3:30). Flagged for Matt to confirm. |
| 2026-08-31 | Widened the three compliance email templates from exemption/variation/appeal to also carry internal_review and formal_review, and gave the internal staff-mailbox notification a conditional recipient — cultural-grounds requests route to the Cultural Advisor mailbox with a referral subject prefix. | #12120, #11050 | The two review tiers Review and Appeal § Part A.2 defines would otherwise fall back to appeal wording in their acknowledgement and outcome emails; the conditional recipient is the platform-side precondition for Granting Exemptions § 3's guarantee that no cultural-grounds request is assessed without Cultural Advisor input (#11050). |
| 2026-08-27 | Widened formType on the compliance-form acknowledgement/outcome templates (#20, #21) from 'exemption' | 'appeal' to also cover 'variation'. | #11878, #11048 | #11745 (#11049) added the two templates for exemption and appeal submissions only; #11048 added the variation compliance-form type and its decision-recording lifecycle, so the same acknowledgement/outcome emails needed to cover it too. |
| 2026-08-23 | Added two member-facing compliance-form email templates (acknowledgement on submission, outcome on decision) to the inventory (#20, #21). | #11745, #11049 | The July 2026 policies promise the submitting member acknowledgement, a reference number and an outcome notification, but only the internal exemptions@/appeals@ staff mailbox was ever emailed (#11049). |
| 2026-07-26 | Add email #19 to the inventory — Membership renewal notice, sent from the Stripe invoice.upcoming webhook via email/templates/subscription-renewal-notice.ts. | #11023, #11017 | PPP's published operational policy commits to emailing subscribed users 2 weeks before the annual membership charge; the email did not exist. It is the only email in the inventory whose existence is an external commitment shown to the AMC, so it is annotated as such. |
| 2026-07-10 | Corrected the ppp-logo-email.png asset-inventory line — the header logo PNG is now 720×240 native (2x of its 360×120 display size) for retina-display sharpness, replacing the prior 360×120 native asset. Display scale in the email shell is unchanged. | #10327, #9821 | The 1x asset rendered soft on retina (>96 DPI) email clients; a 2x PNG keeps the mark crisp. Asset inventory must stay factually accurate as the source of truth. |
| 2026-06-09 | Embed the header logo inline by Content-ID (cid:) instead of a remote URL, with a brand-styled alt-text fallback, so it displays in image-blocking clients without the recipient trusting the sender; document SPF/DKIM/DMARC (incl. ACS) coverage. | #8403, #8319, #8322 | Matt's "no logo" reports were client-side remote-image blocking (Apple Mail/Outlook), not an asset bug. Inline (CID) attachments render without the sender being trusted. BIMI/VMC explicitly not pursued (cost + trademark + only adds a sender avatar). |
| 2026-06-09 | Migrated the four remaining transactional link/email paths that still hardcoded the dead orphan host app.professionalperformanceportfolio.com (Cloudflare Error 1000) onto getWebAppBaseUrl() (WEB_APP_BASE_URL → ppp-uat./ppp.) — the WBA assessor email (activitiesWorkflow), the training-verification approval link (passportTrainingService), the hospital accept-invite deep links (hospitalInviteService), and the medical-passport share URL (medicalPassport, which previously had no env fallback at all). The two module-scope APP_BASE_URL constants were removed and the lookup made lazy so importing the service no longer evaluates the env var at module load. Asset-hosting decision in this spec updated to record the managed-host (WEB_APP_BASE_URL) standard. The previously-unset EMAIL_ASSET_BASE_URL (root cause of the #8319 "no logo" defect) is now wired into the deployed backend by the Azure Pulumi stack — derived from the same host as WEB_APP_BASE_URL — and set in the Doppler ppp/* configs for local dev. Separately, the orphan app. host is adopted into the Cloudflare Pulumi stack as a production-only managed alias so old in-the-wild app. links stop dead-ending on Error 1000. | #8365, #8360 | Follow-up to #8320/#8354 — the same dead app. host survived as the fallback in four other email/link paths, each a latent showstopper. Resolves the whole hardcoded-host class so no sibling transactional email dead-ends on Error 1000. |
| 2026-06-09 | Registration email brought on-brand and made deliverable. The shared BRAND token primary is now PPP brand blue #117BE5 (COLORS.ppp.primary) instead of the off-brand Tailwind #2563eb, with a new darkBlue #003977 token for headings/anchors. Every email footer now links the public Privacy Policy and Terms pages (new marketingBaseUrl/privacyPath/termsPath tokens). The registration-link email now resolves its CTA host via getWebAppBaseUrl() instead of the hardcoded app.professionalperformanceportfolio.com, which is an orphan host with no Cloudflare DNS record (Error 1000) that dead-ended every registration email. | #8354, #8319, #8320, #8322 | UAT bug reports — registration email CTA read off-brand (#8319), the registration link pointed at a dead host (#8320), and the email lacked compliance footer links / showed no logo because the asset host was unreachable (#8322). |
| 2026-06-01 | Header logo in the branded email shell enlarged from 240×80 to its full native 360×120 (3:1) so the PPP mark is the dominant branded element above the AMC accreditation badge. renderLogo() now emits explicit width="360" height="120" plus inline max-width:360px for reliable Outlook/Gmail rendering. | #7868, #7853 | Matt's #7853 feedback (Dev Session 2026-05-13 PM §00:06:07) — the AMC badge still looked bigger than PPP's, so the email "looked like an AMC email, didn't look like our email". The #7316 bump to 240×80 was insufficient. |
| 2026-05-22 | SGD audit 2026-05-13 (evening): add AC email.branding.header-logo-size — PPP logo in email shell must be comparable in scale to AMC and peer professional bodies. | #0, #7316 | Matt reviewed the CPD authorisation email during the session and noted the header logo was too small, making the email look like an AMC email rather than a PPP email. |
| 2026-05-06 | CPD provider-approval email migrated to branded shell (email/templates/cpd-approval.ts); legacy getCpdApprovalEmailContent deleted. | #5769, #5762, #5754 | Logo was broken in production (resolved to a dead Google Drive URL), the template bypassed the brand shell, and the salutation ran into the body without a paragraph break. Surfaced during UAT QA on 2026-05-06. |
| 2026-04-21 | Triage sweep — 4 open issues mapped to this spec | #5189, #4945, #4832, #4831 | Unblocks drift detection on the features index. |
| 2026-04-13 | Initial spec — branded email template system, shell contract, asset hosting on Cloudflare Pages, email inventory of 17 flows | #4942 | Matt's #4569 report surfaced that the welcome email had no branding; audit found the emblem+company-name partial was copy-pasted across 7 templates and 10+ services send inline HTML emails with no shared shell. |