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]

🦋 Changeset detected

Latest commit: 38c349a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stackoverflow/stacks-email	Major

Not sure what this means? Click here to learn what changesets are.

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

[netlify]

✅ Deploy Preview for stacks ready!

Name	Link
🔨 Latest commit	38c349a
🔍 Latest deploy log	https://app.netlify.com/projects/stacks/deploys/6a61164c00865900089a3386
😎 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.

[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]

I pushed a few follow-up fixes:

• Made @stackoverflow/stacks-email publishable outside the repo, including a changeset
• Safely validated custom asset URLs
• Fixed component props being silently ignored
• Made gallery MJML reflect the selected target
• Added regression and catalog-wide tests, now run in CI

The package, docs build, type checks, lint, tests, and external-consumer smoke test all pass.

@abovedave when you have a moment, can you take a moment to verify that these changes match the intention of the PR (especially the publishing of @stackoverflow/stacks-email and the gallery MJML change)? If it all looks good, feel free to merge!