# ng-email documentation Every page of https://yshashi.github.io/ng-email/docs, in reading order. # Introduction ng-email lets you write HTML emails as standalone Angular components and render them into the table-based, inline-styled HTML that email clients expect. Email HTML is its own dialect. Layout is nested tables, styles must be inline, Outlook ignores padding on links, and some clients strip `` styles. ng-email puts those rules into a small set of components, so you write Angular templates with signal inputs and get markup that holds up in the inbox. ```angular-ts @Component({ selector: 'welcome-email', imports: [EMAIL_COMPONENTS], template: `

Welcome, {{ name() }}

Open dashboard
`, }) export class WelcomeEmail { readonly name = input.required(); readonly url = input.required(); } ``` ```ts const { html, text } = await renderEmailBoth(WelcomeEmail, { inputs: { name: 'Ada', url: 'https://example.com/app' }, }); ``` ## What you get - **Components for email layout.** Fifteen primitives, including `Html`, `Body`, `Container`, `Section`, `Row`, `Column`, `Text`, `Heading`, `Button` and `Img`. Each renders the email-safe markup for its job. They are attribute components on real elements (``), so no custom tags reach the inbox. - **A renderer.** `renderEmail()` turns a component into a complete HTML document with an XHTML doctype. It removes everything Angular adds (`ng-version`, component hosts, comments) and keeps Outlook's conditional comments. `renderEmailText()` produces the plain-text part. - **A CLI.** - `ng-email preview` gives you a live preview with desktop and mobile widths and an X-ray of the table structure. - `ng-email build` bundles your emails into one file that any Node service can import. - `ng-email export` writes static `.html` and `.txt` files. - `ng-email add` copies ready-made blocks into your project. - **Blocks and templates.** Over twenty [copy-paste blocks](https://yshashi.github.io/ng-email/components) and five [complete templates](https://yshashi.github.io/ng-email/templates), each one a self-contained Angular component you own and can edit. ## How it works ng-email renders with Angular's own server renderer, `@angular/platform-server`. No browser is involved. After rendering, it cleans the document: it unwraps component host elements, strips Angular's attributes and comments, and refuses output that contains scripts or component styles. Your component's inputs are set with `ComponentRef.setInput`, so they are type-checked against its signal inputs. Angular's npm packages ship partially compiled, so plain Node can't run them as published. `ng-email build` handles that: it compiles your emails ahead of time and runs the Angular Linker, producing a bundle that runs anywhere Node does. ## Packages | Package | What it does | |---|---| | `@ng-email/render` | `renderEmail`, `renderEmailText`, `renderEmailBoth`, plain-text conversion, the `defineEmails` registry | | `@ng-email/components` | The email components and `EMAIL_COMPONENTS` | | `@ng-email/cli` | The `ng-email` command: `build`, `preview`, `export`, `add` | ## Status ng-email is young (0.x). The rendering pipeline and every component are covered by tests that run in both Angular dev and production mode. The email-client workarounds follow well-known client behavior: presentation tables, padding on cells, the Outlook button fix, and body styles moved to an inner cell. They have **not yet been checked across a full client matrix** such as Litmus or Email on Acid. If something renders wrong in a client, please [open an issue](https://github.com/yshashi/ng-email/issues) with the client and version. ng-email is a community project and is not affiliated with the Angular team or Google. Its component behavior is modeled on [react-email](https://github.com/resend/react-email) and [vue-email](https://github.com/vue-email/vue-email); it is a clean-room implementation. Next: [install ng-email](https://yshashi.github.io/ng-email/docs/installation). # Installation Add ng-email to an existing Angular project or to any TypeScript project that will render emails. ## Requirements | | Version | |---|---| | Angular | 22 (`@angular/core`, `common`, `platform-browser`, `platform-server`) | | TypeScript | 6.0 | | Node | 22.22.3+, 24.15+ or 26+ | ## Install the packages The renderer and the components are runtime dependencies. The CLI is a dev dependency. ```bash npm install @ng-email/render @ng-email/components ``` ```bash npm install -D @ng-email/cli ``` If your project isn't an Angular app yet, add the Angular packages ng-email needs: ```bash npm install @angular/core@22 @angular/common@22 @angular/platform-browser@22 @angular/platform-server@22 rxjs ``` ```bash npm install -D @angular/compiler@22 @angular/compiler-cli@22 typescript@~6.0 ``` ## TypeScript configuration `ng-email build` and `ng-email preview` compile your emails with the nearest `tsconfig.json`. Any Angular 22 workspace config works. For a standalone setup, this is enough: ```json { "compilerOptions": { "target": "ES2022", "module": "ES2022", "moduleResolution": "bundler", "lib": ["ES2022", "DOM"], "strict": true, "skipLibCheck": true, "noEmit": true }, "angularCompilerOptions": { "strictTemplates": true } } ``` With `strictTemplates`, template mistakes such as a misspelled input or a wrong type fail the build instead of producing a broken email. ## Where to put your emails A common layout is one folder with an entry file that lists every email: ```text src/emails/ index.ts ← exports the emails (an ng-email "registry") welcome.email.ts receipt.email.ts blocks/ ← blocks added with `ng-email add` ``` Next: [build your first email](https://yshashi.github.io/ng-email/docs/first-email). # Your first email Write a welcome email, preview it in the browser, and render it from a Node script. This takes about ten minutes. This guide assumes you have [installed](https://yshashi.github.io/ng-email/docs/installation) the packages. ## 1. Write the component An email is a standalone component. Import `EMAIL_COMPONENTS` and build the template from the email components. Every value that changes per recipient is a signal input. ```angular-ts // src/emails/welcome.email.ts import { Component, input } from '@angular/core'; import { EMAIL_COMPONENTS } from '@ng-email/components'; @Component({ selector: 'welcome-email', imports: [EMAIL_COMPONENTS], template: ` Welcome to Acme

Welcome, {{ name() }}

Your workspace is ready. Here is where to start.

Open your dashboard
`, }) export class WelcomeEmail { readonly name = input.required(); readonly url = input.required(); } ``` A few things to notice: - ``, `` and `` build the document skeleton, including the metas email clients need. - `` sets the inbox preview text, the line shown under the subject. - `` centers the content at up to 600px, the standard email width. - Styles go in `[ngeStyle]`, never in component `styles`. See [Styling](https://yshashi.github.io/ng-email/docs/styling). ## 2. List your emails Create an entry file that exports a registry. `previewInputs` are the sample values the preview uses. They are type-checked against the component's inputs. ```ts // src/emails/index.ts import { defineEmail, defineEmails } from '@ng-email/render'; import { WelcomeEmail } from './welcome.email'; export { WelcomeEmail }; export const emails = defineEmails({ welcome: defineEmail(WelcomeEmail, { previewInputs: { name: 'Ada', url: 'https://example.com/app' }, description: 'Sent after sign-up', }), }); ``` ## 3. Preview it ```bash npx ng-email preview src/emails/index.ts ``` Open `http://127.0.0.1:3000`. Every save rebuilds the preview. Switch between desktop and mobile widths, read the plain-text part, and turn on **X-ray** to see the table structure ng-email generated. If you break the template, the compile error shows in the page, and the last good version stays visible. ## 4. Build it for your service ```bash npx ng-email build src/emails/index.ts -o dist/emails.mjs ``` This compiles the emails ahead of time and bundles them, Angular included, into a single file. The file also re-exports the render functions. ## 5. Render it ```ts // scripts/try-email.mjs import { renderEmailBoth, WelcomeEmail } from '../dist/emails.mjs'; const { html, text } = await renderEmailBoth(WelcomeEmail, { inputs: { name: 'Grace', url: 'https://example.com/app' }, }); console.log(html.slice(0, 200)); console.log(text); ``` > **Import the render functions from the bundle,** not from `@ng-email/render`. The bundle contains the compiled, linked copy of Angular that your emails were built with. A second, separately imported copy can't render them. Next: [send it](https://yshashi.github.io/ng-email/docs/sending), or learn what the renderer guarantees in [Rendering](https://yshashi.github.io/ng-email/docs/rendering). # Rendering Turn a component into email HTML and plain text, and learn what the renderer guarantees. ## The three functions ```ts import { renderEmail, renderEmailText, renderEmailBoth } from './dist/emails.mjs'; const html = await renderEmail(WelcomeEmail, { inputs: { name: 'Ada' } }); const text = await renderEmailText(WelcomeEmail, { inputs: { name: 'Ada' } }); const both = await renderEmailBoth(WelcomeEmail, { inputs: { name: 'Ada' } }); // { html, text } ``` Prefer `renderEmailBoth` when you send both parts: it renders once and derives the text from that render. Import these from your [`ng-email build`](https://yshashi.github.io/ng-email/docs/cli#ng-email-build) bundle, as shown above. The bundle re-exports them alongside your emails. ## Options | Option | Type | | |---|---|---| | `inputs` | object | Values for the component's signal inputs, type-checked against them. Unknown names are rejected before rendering. | | `providers` | `Provider[]` | Providers for this render, for example a service your email injects. | | `doctype` | `string \| false` | Doctype for full documents. Defaults to XHTML 1.0 Transitional. `false` omits it. | | `htmlToText` | `HtmlToTextOptions` | For `renderEmailText` and `renderEmailBoth`: options passed to html-to-text. | ```ts await renderEmail(InvoiceEmail, { inputs: { invoiceId: 'INV-2041' }, providers: [{ provide: LOCALE_ID, useValue: 'de-DE' }], }); ``` ## What the renderer guarantees - **A clean document.** No `ng-version`, `_ngcontent`, `ng-reflect-*` or hydration attributes. No component host tags: any element with a hyphen in its name is unwrapped. No Angular comments. - **Outlook comments kept.** `` blocks survive, because email clients rely on them. - **The doctype only where it belongs.** Output that starts with `` gets the doctype. A fragment, such as a single block, doesn't. - **Finished async work.** Rendering waits until the app is stable, so data loaded with `resource()` or tracked by `PendingTasks` is in the output. - **Errors reject.** An error thrown while rendering, or a missing required input, rejects the promise. You never get half an email. - **No silent style loss.** Component `styles`/`styleUrl` raise an error instead of disappearing. See [Styling](https://yshashi.github.io/ng-email/docs/styling). ## Errors The renderer's own checks throw `EmailRenderError` with a `code`: | Code | Meaning | |---|---| | `NOT_A_COMPONENT` | The class passed in isn't an Angular component. | | `UNKNOWN_INPUT` | `inputs` contains a name the component doesn't declare. | | `COMPONENT_STYLES` | A rendered component declares `styles` or `styleUrl`. | | `SCRIPT_IN_OUTPUT` | The output contains a `