DocsReference
CLI
The ng-email command from @ng-email/cli.
npm install -D @ng-email/clinpx ng-email --helpng-email build
Compile your emails and bundle them into one ES module that any Node service can import.
npx ng-email build src/emails/index.ts -o dist/emails.mjsThe build:
- compiles everything the entry imports with Angular's AOT compiler, type-checking templates;
- bundles it with esbuild, running the Angular Linker over Angular and any other partially compiled library;
- re-exports
renderEmail,renderEmailText,renderEmailBoth,toPlainText,EmailRenderError,defineEmailanddefineEmails.
Your service renders with the same Angular instance the emails were compiled against. A template error fails the build and prints Angular's diagnostic.
| Option | Default | |
|---|---|---|
-o, --outfile <file> |
dist/emails.mjs |
Output bundle |
-p, --tsconfig <file> |
nearest to the entry | Compiler options, including angularCompilerOptions |
--dev |
off | Keep Angular dev mode (full error messages) |
--minify |
off | Roughly halves the size |
--sourcemap |
off | Write a .map file |
--external <pkg> |
none | Leave a dependency as a runtime import (repeatable). Angular and @ng-email/* can't be external. |
--no-dts |
Skip emails.d.mts |
ng-email preview
A live preview in the browser that rebuilds on every save. See Previewing and exporting.
npx ng-email preview src/emails/index.ts| Option | Default | |
|---|---|---|
--port <n> |
3000 |
0 picks a free port |
--host <addr> |
127.0.0.1 |
Interface to listen on |
--no-dev |
dev mode on | Preview in production mode |
-p, --tsconfig <file> |
nearest |
ng-email export
Render every email to <name>.html and <name>.txt, using its preview inputs.
npx ng-email export src/emails/index.ts -o out| Option | Default | |
|---|---|---|
-o, --outdir <dir> |
out |
Output folder |
-p, --tsconfig <file> |
nearest | |
--dev |
off | Angular dev mode |
The command exits with code 1 if any email fails to render.
ng-email add
Copy blocks and templates from the ng-email registry into your project. See Blocks and templates. Available from @ng-email/cli 0.2.0.
npx ng-email add header-centered welcome| Option | Default | |
|---|---|---|
-d, --dir <dir> |
src/emails/blocks |
Where files are written |
--list |
List the registry | |
--overwrite |
off | Replace existing files |
--registry <url|folder> |
the ng-email website | Also settable with NG_EMAIL_REGISTRY |
ng-email check
npx ng-email check src/emails/index.tsRenders every email with its preview inputs and reports inbox problems: HTML over Gmail's 102 kB clipping limit, images without alt, relative links, flexbox and more. See the full list. Exits with 1 when an email has an error, so it can run in CI. Available from 0.3.0.
| Option | Default | |
|---|---|---|
--name <email> |
all | Check one email (repeatable) |
-p, --tsconfig <file> |
nearest |
ng-email mcp
npx -y @ng-email/cli mcpRuns the MCP server for AI agents on stdio. See AI and agents for how to connect it. Available from 0.3.0.
| Option | Default | |
|---|---|---|
--registry <url|folder> |
the ng-email website | Registry for the block tools |
Programmatic API
Everything the CLI does is available from @ng-email/cli:
import { buildEmails, exportEmails, startPreview, addBlocks } from '@ng-email/cli';
const build = await buildEmails({ entry: 'src/emails/index.ts', outfile: 'dist/emails.mjs', minify: true });
// → { outfile, dtsFile, bytes, durationMs, mode }
const exported = await exportEmails({ entry: 'src/emails/index.ts', outdir: 'out' });
// → { outdir, written, failed }
const preview = await startPreview({ entry: 'src/emails/index.ts', port: 0 });
console.log(preview.url);
await preview.close();| Export | |
|---|---|
buildEmails(options) |
ng-email build; throws BuildError (with details) on failure |
exportEmails(options) |
ng-email export |
startPreview(options) |
ng-email preview; returns { url, state(), rebuild(), close() } |
addBlocks(options), listRegistry(registry?) |
ng-email add; throws RegistryError |
loadCatalog(bundleUrl) |
Lists and renders the emails in a built bundle |
renderEntry(options) |
Builds an entry in memory, then renders and checks its emails |
checkEmailHtml(html, text?) |
The ng-email check rules, on any HTML |
createMcpServer(options?), runMcpServer(options?) |
The MCP server, to embed or run |
angularLinkerPlugin({ cache? }), createLinkerCache() |
The esbuild plugin that links Angular, for your own builds |