Skip to content
View in Notion

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 ​

#QuestionRefProposed answer
1Matt 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?#7853Adopted 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.ts on 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 export

Shell contract ​

ts
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)
}): string

Rules 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> with display: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) ​

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).

  • _headers rule sets Cache-Control: public, max-age=31536000, immutable on /email-assets/*
  • EMAIL_ASSET_BASE_URL resolves to the managed host's /email-assets path — 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_URL now 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 as WEB_APP_BASE_URL). The Doppler ppp/* configs (used for local dev) also carry it. The earlier intent of pointing it at the dead app. host is retired (#8360)
  • The existing PPP_LOGO_URL env var and GOOGLE_DRIVE_FALLBACK constant 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 by pnpm --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 the app. host did (#8320).
  • The shell renders <img src="cid:ppp-logo-email"> (shell.ts renderLogo). mailer-helper.ts sendEmail auto-attaches the bytes as an inline attachment (ACS EmailAttachment.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 alt text 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. The spf.protection.outlook.com include 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 toward p=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 ​
#FlowTriggerCurrent locationMigrated in
1Welcome (full account)authService.signUpauthService/index.ts (inline)#4943
2Pending accountauthService.signUp when hospital_staffauthService/index.ts (inline)#4943
3Password resetBetter Auth callbackemail-templates.ts#4944
4CPD approvalcpdUserActivities.approveCpdActivityemail/templates/cpd-approval.ts#5762
5Timesheet batch approvaltimesheetBatchWorkflowemail-templates.ts#4944
6Payroll admin timesheet approvedtimesheetPayrollemail-templates.ts#4944
7Admin officer timesheet forwardedtimesheetBatchWorkflowemail-templates.ts#4944
8360 reviewerppp360Serviceemail-templates.ts#4944
9Registration linksendRegistrationLinkauthService/sendRegistrationLink.ts (inline)#4945
10Hospital invitehospitalInviteServicehospitalInviteService/index.ts (inline)#4945
11CPD plan submission remindercpdPlanService/notificationsubmissionReminder.ts (inline)#4946
12CPD activity createdcpdUserActivities.emailOnCreatecpdUserActivities/index.ts (inline)#4946
13Appraisal notificationscheduledNotificationServiceprocessAppraisalNotifications.ts (inline)#4946
14Support FAQ questionsupportServices.faqQuestionsupportServices/faqQuestion.ts (inline)#4947
15Support FAQ answersupportServices.faqAnswersupportServices/faqAnswer.ts (inline)#4947
16Roster managementhospitalAdminRosterServicerosterManagement.ts (inline)#4947
17GMC validation noticegmcRegistrantServicefetchGmcRegistrantDirect.ts (inline, audit)#4947
18Logbook case pending reviewactivitiesService.notifyAssessorOnLogbookSubmissionemail/templates/logbook-assessor.ts#9189
19Membership renewal noticerenewalNoticeService.handleUpcomingInvoiceemail/templates/subscription-renewal-notice.ts#11017
20Compliance form (exemption/variation/internal review/formal review/appeal) member acknowledgementcomplianceFormService.submitComplianceFormemail/templates/compliance-form-acknowledgement.ts#11049, #11048, #11050
21Compliance form (exemption/variation/internal review/formal review/appeal) member outcomecomplianceFormService.notifyComplianceFormDecisionemail/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 ​

UseNot
sign inlog in / login
sign upregister (when referring to creating an account; "regulatory registration" is distinct)
Professional Performance PortfolioPPP (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 Portfolio beats Click 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 new email/templates/logbook-assessor.ts flow), mirroring the WBA assessor email. Delivery is best-effort and never blocks the submit. Behaviour and the assessor-routing semantics are specified in logbook.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_URL and GOOGLE_DRIVE_FALLBACK are deleted
  • ⏳ email-shell-gate CI 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_URL set in Doppler uat + prod
  • ⏳ system-emails.feature has one @smoke scenario 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 ​
DateChangePR/IssueReason
2026-10-05The 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, #12936Rob 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-31Widened 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, #11050The 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-27Widened 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-23Added two member-facing compliance-form email templates (acknowledgement on submission, outcome on decision) to the inventory (#20, #21).#11745, #11049The 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-26Add email #19 to the inventory — Membership renewal notice, sent from the Stripe invoice.upcoming webhook via email/templates/subscription-renewal-notice.ts.#11023, #11017PPP'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-10Corrected 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, #9821The 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-09Embed 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, #8322Matt'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-09Migrated 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, #8360Follow-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-09Registration 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, #8322UAT 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-01Header 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, #7853Matt'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-22SGD 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, #7316Matt 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-06CPD provider-approval email migrated to branded shell (email/templates/cpd-approval.ts); legacy getCpdApprovalEmailContent deleted.#5769, #5762, #5754Logo 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-21Triage sweep — 4 open issues mapped to this spec#5189, #4945, #4832, #4831Unblocks drift detection on the features index.
2026-04-13Initial spec — branded email template system, shell contract, asset hosting on Cloudflare Pages, email inventory of 17 flows#4942Matt'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.

Internal documentation — org members only