Comms Arc 1: Unified Sender + Branded Template Shell
What & Why
Today the app sends from two different addresses ( for ~18 templates and for one), every template has its own hand-rolled HTML header/footer/colors, and the brand string varies between "Canadian Elite Volleyball Academy" and other phrasings. Footers tell families "Please do not reply." That blocks every part of the bigger plan: replies can't be threaded if there's no canonical sender, families won't reply if we tell them not to, and the templates can't be made to "look the same" without a shared layout. This task collapses all of that into one consistent, branded outbound surface: every email goes from with a matching , every email is wrapped in one shared layout component, and every footer invites a reply because the inbox work in the next arc will route those replies into the app.
Done looks like
- Every email the app sends — every transactional, every reminder, every digest, every admin-bulk send, the SOF feedback flow, the new pipeline test, all 19+ templates — uses one canonical sender: with .
- A single shared layout helper renders every email's header (logo + brand bar), body slot, and footer (academy name, contact line, "Reply to this email — we read every one", unsubscribe link where the email type warrants one). Templates supply only their unique body content; nothing template-side controls header/footer/branding/colors.
- Visual brand is consistent across templates: same color palette, same typography, same spacing rhythm, same call-to-action button style. Pulled from the existing app palette so emails match the in-app look.
- Brand display name in templates standardized to "Volleyball Elite Academy" (matches local usage and the domain). The legacy sender is retired from code defaults; any code path that previously fell back to that string now falls back to the new canonical sender.
- "This is an automated message. Please do not reply" footer copy is removed everywhere; replaced with "Reply to this email and a member of our team will get back to you" (or the unsubscribe-applicable variant for marketing-class emails).
- The Communication Hub's "from address" field for admin bulk sends defaults to the new canonical sender; the field is still editable but the placeholder/help text reflects the new default.
- A short rendering test renders each major template through the shared layout and asserts the header brand string, sender display name, reply-to, and footer copy are all the new canonical values — so a future hand-edit to a template can't silently bypass the layout.
Out of scope
- Setting up inbound email or building the Conversations view (Arc 2).
- AI-drafted replies (Arc 3).
- Migrating any existing audience off — there's no subscriber list tied to that address; it was only a sender identity.
- Building an unsubscribe management UI. Existing unsubscribe links continue to work; no new flow.
- Changing scheduler timing, recipient logic, or the email-log schema.
- Touching the domain DNS (currently points at Corsizio per the user). The retirement is purely in code defaults.
Pre-flight (admin action, not code)
- The user verifies in the Resend dashboard with the DNS records Resend provides (SPF, DKIM x3, return-path MX, recommended DMARC). Code in this task ships independently of that verification — the From change is safe to merge before DNS is green; sends will still succeed but with weaker authentication until DNS verification completes.
Steps
1.
Brand + sender constants — Introduce a single source-of-truth module exporting the canonical from-address, reply-to, brand display name, brand short name, contact email, and brand color tokens. All future code reads these constants; no string literals. 2.
Shared email layout helper — A server-side function that takes a shape and returns a complete HTML document with the canonical header (logo, brand bar), body slot, and footer (academy address line, "reply to this email" invitation, unsubscribe slot when ). Use inline styles (email-client compatible) keyed off the brand color tokens. Provide a parallel plain-text helper that produces the matching plain-text version so multipart emails stay aligned. 3.
Refactor every template through the layout — Walk every inlined HTML block in (and any other file that builds an outbound HTML body), extract just the unique body content, and route it through the shared layout. Strip the now-duplicate header/footer/wrapper HTML from each template. Same pass for plain-text bodies via the plain-text helper. 4.
Sender + reply-to sweep — Replace every literal that defaults to the legacy sender with the new canonical sender constant. Add (the canonical reply-to constant) to every Resend send call site. The admin bulk-send field's default now reads the constant. 5.
Footer copy sweep — Remove every "this is an automated message, please do not reply" string. Replace with the appropriate footer variant from the layout helper. The SOF feedback flow's existing reply-button URL keeps working but the surrounding "do not reply" copy goes. 6.
Brand string sweep — Standardize the visible brand name in template body content to "Volleyball Elite Academy". Display name in From headers and layout header uses the brand-name constant so a future rename is a one-line change. 7.
Tests — A rendering test that, for each of the 19 templates, asserts: layout wraps the body, From string equals the canonical sender, Reply-To equals the canonical reply-to, footer contains the new "reply to this email" line and not the old "do not reply" line, body still contains the template's unique signal content. Plus a guard test that grep-asserts no source file under contains the legacy sender literal or the legacy footer copy outside of allowed locations (e.g. comments documenting the migration). 8.
Docs — Update with a "Email branding" subsection: where the constants live, where the layout helper lives, the rule that templates must go through the layout, and a note that DNS verification of happens in the Resend dashboard.
Architectural constraints:
- The layout helper is the only producer of full email HTML/text. Templates produce body fragments only. Enforce this with the grep guard test.
- Inline styles only. No blocks. No external CSS. Email clients (Gmail, Outlook, iOS Mail) don't reliably honor either.
- Do not introduce a new email-rendering library or templating engine. Keep it plain TypeScript template literals routed through the layout helper — matches the existing codebase, zero new dependencies.
- Do not change the email-log schema, recipient resolution, scheduling, or webhook handling. This task is presentation + sender identity only.
Relevant files
- - - - - -
No comments:
Post a Comment