Mailcraft

Mailcraft is a sender-agnostic SDK that turns intent into polished, on-brand transactional emails.

Monorepo Packages

  • @mailcraft/types: shared SDK contracts
  • @mailcraft/core: brand engine, archetypes, and rendering primitives
  • @mailcraft/theme-pack: open-source Step Zero archetype React Email pack
  • @mailcraft/adapter-resend: Resend sender adapter
  • @mailcraft/adapter-ses: AWS SES sender adapter
  • @mailcraft/adapter-brevo: Brevo (Sendinblue) sender adapter
  • @mailcraft/sdk: public send/render API
  • @mailcraft/preview: local preview server

Quick Start For Consumers

Install only what your app needs.

pnpm add @mailcraft/sdk @mailcraft/adapter-resend

Create a Mailcraft instance and send a welcome email:

import { Mailcraft, type BrandProfile } from "@mailcraft/sdk";
import { ResendAdapter } from "@mailcraft/adapter-resend";

const brand: BrandProfile = {
  name: "Acme",
  sender: {
    fromEmail: "noreply@acme.com",
    fromName: "Acme Team"
  },
  business: {
    legalName: "Acme Inc."
  }
};

const mailcraft = new Mailcraft(brand);
const adapter = new ResendAdapter(process.env.RESEND_API_KEY);

await mailcraft.send(
  "welcome",
  {
    to: ["user@example.com"],
    title: "Welcome to Acme",
    body: "Thanks for joining."
  },
  adapter
);

Adapter packages:

  • @mailcraft/adapter-resend
  • @mailcraft/adapter-ses
  • @mailcraft/adapter-brevo

Local Release Testing With Verdaccio (Optional)

Verdaccio is for local package-release testing by maintainers. Regular consumers should install from the default npm registry.

Use this only when validating unpublished local versions.

Add this to your app .npmrc:

@mailcraft:registry=http://localhost:4873

Then install pinned local versions:

pnpm add @mailcraft/sdk@0.1.0 @mailcraft/adapter-brevo@0.1.0

Documentation

  • Quick start: docs/QUICKSTART.md
  • API reference: docs/API_REFERENCE.md
  • CLI guide: docs/CLI.md
  • Adapter integration: docs/adapters/INTEGRATION_GUIDE.md

Maintainer Workflow

For maintainers working in this monorepo:

  1. Install dependencies:
pnpm install
  1. Build all packages:
pnpm run build
  1. Run preview server:
pnpm run dev:preview
  1. Open web docs:
pnpm run dev:docs

Then visit http://localhost:4040/docs.

Step Zero Validation

  • Checklist: docs/validation/acceptance-checklist.md
  • Scorecard: docs/validation/step-zero-scorecard.md

MCP Server For AI Email Drafting

Mailcraft now includes an MCP server so AI clients can use the SDK as structured tools instead of guessing at raw HTML.

Available tools:

  • list_mailcraft_archetypes: explain which email archetype fits the business goal
  • create_brand_profile: turn business details into a reusable Mailcraft brand profile
  • draft_business_email: turn a business brief into a suggested archetype plus typed Mailcraft input
  • render_business_email: render the final subject, HTML, and plain text output

Run it locally:

pnpm install
pnpm run dev:mcp

Or build and start it:

pnpm build
pnpm run start:mcp

Example MCP client config:

{
  "mcpServers": {
    "mailcraft": {
      "command": "pnpm",
      "args": [
        "--dir",
        "/home/codellyson/workfolder/personal-projects/mailcraft",
        "run",
        "start:mcp"
      ]
    }
  }
}

This lets an AI assistant gather business context, choose an archetype, draft a clean email, and render it through Mailcraft.

Deploy Docs To Cloudflare Pages

  1. Authenticate once:
pnpm dlx wrangler login
  1. Build static docs:
pnpm run build:docs:cloudflare
  1. Deploy to Cloudflare Pages:
pnpm run deploy:docs:cloudflare

By default this deploys to the Cloudflare Pages project mailcraft-docs. Override the project name when needed:

CLOUDFLARE_PAGES_PROJECT=my-docs-project pnpm run deploy:docs:cloudflare