Add email docs and stacks-email package

[abovedave]

STACKS-905

Introduces @stackoverflow/stacks-email, a new (experimental) MJML powered email package for building, previewing, documenting, and compiling Stack Overflow email templates.

• A reusable email component library
• A template gallery for complete email examples
• A shared MJML compile pipeline
• Target-specific token replacement for preview, .NET/Razor, and Braze
• A flexible Node/TypeScript package API
• A narrower SvelteKit HTTP compile endpoint for service integration
• Static compiled artifacts for use in stacks-docs

Background

Historically, Stack Overflow's email design system lived across several separate implementations, including the monolith and external marketing tools. Since 2020, the system has had limited modernization or maintenance.

This work is part of the 2026 rebrand rollout. The goal is to create a shared source of truth for email design patterns, implementation, previewing, and downstream consumption.

We selected MJML because it is widely adopted, MIT licensed, and abstracts much of the client-specific complexity of writing production email HTML.

Overview

Components

~/packages/stacks-email/components

Adds reusable email building blocks such as Button, Header, Footer, Card etc. Each defines their variants, options, tokens, and MJML render output in one place.

Templates

~/packages/stacks-email/templates

Adds example and reusable template definitions including Transactional, Newsletter, Promotional. These compose components into full MJML documents and can expose variants and props.

Compile APIs

The package can be consumed in several ways:

• As a local/gallery app for previewing emails (this branch is currently live on email.stackoverflow.com)
• As a Node/TypeScript library via @stackoverflow/stacks-email
• As a deployed SvelteKit endpoint via POST /api/compile
• As static compiled artifacts for docs previews
• As raw MJML or compiled HTML output

The package API and HTTP API intentionally serve different use cases.

The package API is the full in-process integration surface for trusted TypeScript consumers. It supports catalog discovery, component compilation, template compilation, renderable dispatch, and lower-level MJML compilation primitives.

The HTTP endpoint is a narrower service integration surface. It currently focuses on composing transactional emails from a validated JSON block list, then returning compiled MJML and HTML. This keeps the cross-service contract small while still enabling non-TypeScript consumers to generate branded email output without embedding the package.

Documentation

Adds a new Email section to stacks-docs, including:

• Email overview
• Template documentation
• Component documentation
• Embedded email previews
• MJML/HTML output tabs
• Usage examples
• Generated options tables

Usage

As a package

import {
    getEmailCatalog,
    compileEmailTemplate,
    compileEmailComponent,
    compileEmailRenderable,
} from "@stackoverflow/stacks-email";

const email = compileEmailTemplate({
    slug: "transactional",
    target: "braze",
    props: {
        headlineText: "Reset your password",
        ctaText: "Reset password",
    },
});

console.log(email.html);

As an endpoint

curl -X POST https://email.stackoverflow.design/api/compile \
  -H "Content-Type: application/json" \
  --data '{
    "template": "transactional",
    "target": "preview",
    "previewText": "Reset your password",
    "blocks": [
      {
        "type": "headline",
        "props": {
          "textContent": "Reset your password"
        }
      },
      {
        "type": "text",
        "props": {
          "textContent": "Click below to continue."
        }
      },
      {
        "type": "button",
        "props": {
          "href": "[[BUTTON_URL]]",
          "text": "Reset password"
        }
      }
    ]
  }'

As static docs artifacts

@stackoverflow/stacks-email/sveltekit exports route handlers used by stacks-docs to serve precompiled email HTML, MJML, and manifest data.

Compile targets

Every compile supports a target:

• preview: replaces tokens with sample values
• dotnet: replaces tokens with Razor model bindings
• braze: replaces tokens with Braze/Liquid-style values

This allows the same email source to produce output for different downstream systems.

Notes for reviewers

Suggested review path:

1. Start with packages/stacks-email/README.md
2. Review the component structure in packages/stacks-email/components
3. Review template composition in packages/stacks-email/templates
4. Review the compile pipeline in packages/stacks-email/src/lib/pipeline
5. Review public API exports in packages/stacks-email/src/lib/api
6. Review the HTTP endpoint in packages/stacks-email/src/routes/api/compile/+server.ts
7. Review docs integration in packages/stacks-docs/src/components/StacksEmailEmbed.svelte
8. Review static artifact handlers under packages/stacks-docs/src/routes/email/compiled

Current limitations / Follow-ups

• This is mostly experimental but wanted to at least get the design elements and static markup available for consumption.
• Open to ideas for a testing strategy for a follow-up PR.
• The endpoint is intentionally narrower than the package API.
• The package compiles email markup; it does not send emails.
• Real inbox/client testing is still required before using output in production sends (Litmus?).
• Additional templates, variants, and target mappings can be added as rollout needs become clearer.
• Production hosting and ownership model should be finalized separately from this package implementation (hi platform team!)
• Add Figma Code Connect
• Sync with tools e.g., Braze API

[changeset-bot]

⚠️ No Changeset found

Latest commit: f19c383

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

✅ Deploy Preview for stacks ready!

Name	Link
🔨 Latest commit	f19c383
🔍 Latest deploy log	https://app.netlify.com/projects/stacks/deploys/6a56309b0a11260008727bef
😎 Deploy Preview	https://deploy-preview-2292--stacks.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for stackoverflow-email ready!

Name	Link
🔨 Latest commit	f19c383
🔍 Latest deploy log	https://app.netlify.com/projects/stackoverflow-email/deploys/6a56309beb553000095ec5f4
😎 Deploy Preview	https://deploy-preview-2292--stackoverflow-email.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[dancormier]

Really nice work here @abovedave. Adding stacks-email seems reasonable and I think this is looking pretty solid. I noticed a few bugs that I think shouldn't be too tough to handle

Note

I noticed a bunch of whitespace-only changes to a couple of yaml files and undid just the whitespace changes to reduce the noise.

[dancormier]

The README describes email.html as “ready-to-send HTML”, but the default image sources are root-relative /email/… URLs. These images would likely break once sent outside the preview host.

Should we make asset URLs absolute/configurable or clarify that consumers must rewrite/package image assets before sending?

[abovedave]

Ah yes, great point. I've added a concept of a assetBaseUrl which defaults to https://email.stackoverflow.design but can be configured at the server and consumption layers.

I might need to amend this once I get into how tools like Braze ingest these external urls (or say, want assets POST'd).

[abovedave]

f19c383