Skip to content

DocsGuides

Rendering

Turn a component into email HTML and plain text, and learn what the renderer guarantees.

The three functions

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 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.
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. <!--[if mso]>…<![endif]--> blocks survive, because email clients rely on them.
  • The doctype only where it belongs. Output that starts with <html> 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.

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 <script> element.
NO_OUTPUT Angular finished without producing the email.
import { EmailRenderError, renderEmail } from './dist/emails.mjs';

try {
  await renderEmail(WelcomeEmail, { inputs });
} catch (error) {
  if (error instanceof EmailRenderError && error.code === 'UNKNOWN_INPUT') {
    // a caller passed a field the template doesn't have
  }
  throw error;
}

Errors from your own component are rethrown unchanged. In production builds, Angular shortens its errors to codes. For example, NG0950 means a required input wasn't set. Build with --dev to get the full messages.

Plain text

The text part is derived from the rendered HTML:

  • Images are left out.
  • Elements marked data-skip-in-text="true" are left out. The preview text (<nge-preview>) is marked this way.
  • Links render as label url, and just the URL when the label already is the URL.
  • A table marked data-text-format="dataTable" becomes aligned rows.
  • Lines aren't wrapped.
<p data-skip-in-text="true">Only in the HTML version</p>

Pass htmlToText to adjust the conversion. Your selectors are added after the defaults rather than replacing them.

Rendering without the CLI

renderEmail works in any environment where Angular itself runs: Angular's compiler has processed your components (AOT) and the Angular Linker has processed the framework packages. ng-email build does both for you, and its output is tested by rendering from an empty folder with plain node. If you assemble your own build, angularLinkerPlugin() from @ng-email/cli is the esbuild plugin it uses.