Email Generator

A powerful TypeScript wrapper for MJML that simplifies professional email generation with a fluent API, standardised styling, and component-based architecture.

Table of Contents

• Email Generator
  • Table of Contents
  • Installation
  • Quick Start
  • API Reference
    • Core Functions
      • createEmail()
    • EmailBuilder Methods
      • render(options?): RenderResult
      • getMjml(): string
  • Components
    • Section Layout Components
      • newSection(): EmailBuilder
      • endSection(): EmailBuilder
    • Header Component
      • header(title: string, subtitle?: string): EmailBuilder
    • Text Section Component
      • textSection(content: string, title?: string): EmailBuilder
    • Metrics Section Component
      • metricsSection(title: string, metrics: MetricItem[], subtitle?: string): EmailBuilder
    • Table Section Component
      • tableSection(title: string, tableData: TableData, subtitle?: string): EmailBuilder
    • Bar Graph Component
      • barGraphSection(title: string, bars: BarData[], subtitle?: string): EmailBuilder
    • Progress Bar Component
      • progressBarSection(title: string, percentage: number, subtitle?: string): EmailBuilder

Installation

npm install everydayai-email-generator

Quick Start

The Email Generator provides a fluent API for building professional emails with consistent styling and responsive design.

import { createEmail } from 'everydayai-email-generator';

// Create a example email with multiple components
const email = createEmail()
  .newSection()
  .header('Monthly Report', 'Performance summary for December 2024')
  .endSection()
  .newSection()
  .textSection('Thank you for your continued partnership. This is an example of a text section with an optional header included', 'Introduction')
  .metricsSection('Key Performance Indicators', [
    { value: '$125,000', description: '+12% vs last month' },
    { value: '248', description: '+8% growth' },
  ])
  .endSection()
  .newSection()
  .barGraphSection('Quarterly Comparison', [
    { label: 'Q1', value: 85 },
    { label: 'Q2', value: 92 },
    { label: 'Q3', value: 78 }
  ])
  .progressBarSection('Annual Target Progress', 73, 'Goal: $500k by year end')
  .endSection();

// Render to HTML
const result = email.render();

Result:

The resulting HTML can be used with any email service that accepts HTML content and paired with something like Nodemailer to distribute the email.

API Reference

Core Functions

createEmail()

Creates a new EmailBuilder instance with a fluent API for building emails. This is the starting point for building an email.

Returns: EmailBuilder

const email = createEmail();

EmailBuilder Methods

All methods return the EmailBuilder instance for method chaining, enabling a fluent API pattern.

render(options?): RenderResult

Renders the email to HTML using MJML.

Parameters:

• options (RenderOptions, optional): Rendering configuration (advanced usage)

Returns: RenderResult with html string and optional errors array

const result = email.render({ minify: true, beautify: false });

getMjml(): string

Gets the raw MJML markup for the email without rendering to HTML.

Returns: string - The complete MJML document

const mjmlMarkup = email.getMjml();

Components

Section Layout Components

Control the visual grouping and separation of email sections. All components are rendered with white rectangular backgrounds that can be chained together. To create different email sections using visual grouping for separation of content, you can use the newSection() and endSection() methods.

newSection(): EmailBuilder

Starts a new email section with rounded top corners and proper spacing.

Features:

• Creates visual separation from previous content/starts the email
• Rounded top corners only
• Proper margin and padding
• White background

endSection(): EmailBuilder

Ends an email section with rounded bottom corners and proper spacing.

Features:

• Creates visual separation for next content
• Rounded bottom corners only
• Proper margin and padding
• Complements newSection() for grouped content

Example (With and without sectioning): Take this example of a simple email with no sectioning:

const email = createEmail()
      .header('Here\'s some components with no sectioning', 'This is a subtitle')
      .textSection('This is a text section with an optional header included', 'Introduction')
      .metricsSection('Key Performance Indicators', [
        { value: '$125,000', description: '+12% vs last month' },
        { value: '248', description: '+8% growth' },
      ])
      .textSection('This is a text section explaining the bargraph without an optional header included')
      .barGraphSection('Quarterly Comparison', [
        { label: 'Q1', value: 85 },
        { label: 'Q2', value: 92 },
        { label: 'Q3', value: 78 }
      ])

No Sectioning Visual Example:

And now with sectioning:

const email = createEmail()
  .newSection()
  .header('Here\'s some components with no sectioning', 'This is a subtitle')
  .endSection()
  .newSection()
  .textSection('This is a text section with an optional header included', 'Introduction')
  .endSection()
  .newSection()
  .metricsSection('Key Performance Indicators', [
    { value: '$125,000', description: '+12% vs last month' },
    { value: '248', description: '+8% growth' },
  ])
  .endSection()
  .newSection()
  .textSection('This is a text section explaining the bargraph without an optional header included')
  .barGraphSection('Quarterly Comparison', [
    { label: 'Q1', value: 85 },
    { label: 'Q2', value: 92 },
    { label: 'Q3', value: 78 }
  ])
  .endSection()

Sectioning Visual Example:

Header Component

Creates a prominent header section with title and optional subtitle.

header(title: string, subtitle?: string): EmailBuilder

Parameters:

• title (string): The main header text (required)
• subtitle (string, optional): Optional subtitle displayed below the title

Features:

• Large, bold title text
• Left-aligned layout
• Optional subtitle with smaller font
• Consistent spacing and styling

Example:

const email = createEmail()
  .newSection()
  .header('Monthly Performance Report', '2025 Q2')
  .endSection()
  

Visual Example:

Text Section Component

Creates a content section with formatted text and optional title.

textSection(content: string, title?: string): EmailBuilder

Parameters:

• content (string): The main text content (required)
• title (string, optional): Optional section title displayed above content

Features:

• Readable typography with optimal line height
• HTML escaping for security
• Optional section titles
• Responsive text layout

Example:

const email = createEmail()
  .newSection()
  .textSection('Thank you for your continued partnership with our services.')
  .textSection('Our team has been working hard to improve...', 'Updates')
  .endSection()

Visual Example:

Metrics Section Component

Creates a dashboard-style metrics display with cards in a responsive grid layout.

metricsSection(title: string, metrics: MetricItem[], subtitle?: string): EmailBuilder

Parameters:

• title (string): The main section title (required)
• metrics (MetricItem[]): Array of metric objects (required)
• subtitle (string, optional): Optional section subtitle

Features:

• Responsive grid layout
• Card-based design with rounded corners
• Support for metric labels, values, and descriptions
• Consistent spacing and typography

Example:

const email = createEmail()
  .newSection()
  .metricsSection('Key Performance Indicators', [
    { value: '$125,000', description: '+12% vs last month' },
    { value: '248', description: '+8% growth' },
    { value: '3.2%', description: '+0.5% improvement' },
    { value: '42', description: '8 new this month' }
  ], 'Monthly overview')
  .endSection()

Visual Example:

Table Section Component

Creates a professional data table with headers and rows.

tableSection(title: string, tableData: TableData, subtitle?: string): EmailBuilder

Parameters:

• title (string): The main section title (required)
• tableData (TableData): Object containing headers and rows (required)
• subtitle (string, optional): Optional section subtitle

Features:

• Responsive table design
• Header row with distinct styling
• Mobile-friendly layout

Example:

const email = createEmail()
  .newSection()
  .tableSection('Sales Performance', {
    headers: ['Region', 'Sales', 'Growth'],
    rows: [
      { cells: ['North', '$45,000', '+12%'] },
      { cells: ['South', '$38,000', '+8%'] },
      { cells: ['East', '$52,000', '+15%'] },
      { cells: ['West', '$41,000', '+6%'] }
    ]
  }, 'Regional breakdown')
  .endSection()

Visual Example:

Bar Graph Component

Creates a visual bar chart with up to 3 bars using company brand colours.

barGraphSection(title: string, bars: BarData[], subtitle?: string): EmailBuilder

Parameters:

• title (string): The main section title (required)
• bars (BarData[]): Array of bar data objects, maximum 3 bars (required)
• subtitle (string, optional): Optional section subtitle

Features:

• Automatic scaling relative to largest value
• Company brand colours (blue, green, orange)
• Responsive bar sizing
• Label and value display
• Maximum of 3 bars for optimal readability

Example:

const email = createEmail()
  .newSection()
  .barGraphSection('Quarterly Comparison', [
    { label: 'Q1', value: 85, subtitle: 'Strong start' },
    { label: 'Q2', value: 92, subtitle: 'Peak performance' },
    { label: 'Q3', value: 78, subtitle: 'Seasonal dip' }
  ], 'Performance by quarter')
  .endSection()

Visual Example:

Progress Bar Component

Creates a visual progress indicator showing percentage completion.

progressBarSection(title: string, percentage: number, subtitle?: string): EmailBuilder

Parameters:

• title (string): The main section title (required)
• percentage (number): Progress percentage from 0-100 (required)
• subtitle (string, optional): Optional section subtitle

Features:

• Orange fill colour matching brand
• Rounded rectangle design
• Percentage validation (0-100)
• Smooth visual progression
• Clear percentage display

Example:

const email = createEmail()
  .newSection()
  .progressBarSection('Annual Target Progress', 73)
  .endSection()

Visual Example: