tzMail

A powerful and flexible TypeScript/Node.js email package built on top of Nodemailer, featuring a robust templating system with built-in themes, caching, and easy attachment management.

Features

• 🚀 Singleton Factory: Easy initialization and global access.

• 🎨 Themed Templates: 5 built-in professional themes (Modern, Corporate, Minimal, Monokai, System).

• 🌓 Dark Mode Support: All templates support light and dark variants.

• ⚡ Performance: In-memory template caching with TTL and version history.

• 📎 Attachment Service: Simple helpers for local files and buffers.

• ✅ Validation: Built-in configuration validation for templates.

Installation

npm install tzmail
# or
yarn add tzmail

Quick Start

1. Initialize the Factory

import { EmailFactory } from 'tzmail';

const smtpConfig = {
  host: 'smtp.example.com',
  port: 587,
  auth: {
    user: '[email protected]',
    pass: 'password'
  },
  defaultFrom: 'My App <[email protected]>'
};

const emailFactory = EmailFactory.initialize(smtpConfig);

2. Create and Send an Email

const templateService = emailFactory.getTemplateService();

// Create a template
const welcomeTemplate = templateService.createTemplate(
  'modern', // ThemeType
  'light',  // Variant
  {
    body: {
      title: 'Welcome!',
      message: 'Thanks for joining us.',
      buttonText: 'Get Started',
      buttonUrl: 'https://myapp.com'
    }
  }
 );

// Send the email
const result = await emailFactory.sendEmail({
  to: '[email protected]',
  subject: 'Welcome aboard!',
  template: welcomeTemplate
});

console.log(result.success ? 'Sent!' : 'Failed');

Core Components

Themes

| Theme | Best For | Features | | --- | --- | --- | | MODERN | Modern UI apps | Gradients, glassmorphism, rounded corners. | | CORPORATE | Business/Enterprise | Serif typography, gold accents, structured layout. | | MINIMAL | Clean newsletters | High whitespace, focused content, neutral colors. | | MONOKAI | Technical content | Syntax highlighting for code blocks, vibrant colors. | | SYSTEM | General purpose | Clean, accessible, system-native look. |

Attachment Service

Easily add attachments from paths or buffers:

const attachmentService = emailFactory.getAttachmentService();
const file = await attachmentService.addFromPath('path/to/report.pdf');

await emailFactory.sendEmail({
  to: '[email protected]',
  subject: 'Monthly Report',
  attachments: [file],
  html: '<p>Please find the report attached.</p>'
});

Configuration Reference

ITemplateConfig

Customize your email structure:

• header: { show: boolean, logo: { type: 'text' | 'image', ... } }

• body: { title, message, buttonText, buttonUrl, alignment, ... }

• footer: { show: boolean, links: [], socialLinks: [], copyrightText }

• layout: 'full' | 'minimal'

• spacing: 'compact' | 'normal' | 'relaxed'

Error Handling

The sendEmail method returns a result object:

{
  success: boolean;
  messageId?: string;
  response?: string;
  error?: any;
}