✉️ MailCraft

A lightweight, TypeScript-friendly Node.js mailer that supports HTML templates with inline styling, custom template directories and optional custom render functions. Built for simplicity, flexibility and developer-friendly usage.

Why MailCraft?

MailCraft simplifies sending production-grade emails with:

• Multiple template sources (string, file path, or directory)
• Automatic CSS inlining for email client compatibility
• Built-in security (HTML escaping + path traversal protection)
• Attachment support
• Full TypeScript definitions
• Pluggable rendering engine
• Lightweight and dependency-minimal

Installation

npm install mailcraft-lite

Quick Start

import { createMailer } from 'mailcraft-lite';

const mailer = createMailer({
  smtp: {
    host: 'smtp.gmail.com',
    port: 587,
    secure: false,
    auth: {
      user: '[email protected]',
      pass: 'your-app-password'
    }
  },
  from: '[email protected]',
  templateDir: './templates'
});

await mailer.send({
  to: '[email protected]',
  subject: 'Welcome to MailCraft!',
  templateName: 'welcome.html',
  data: {
    name: 'John Doe',
    confirmationLink: 'https://example.com/confirm/123'
  }
});

Configuration

Basic Configuration

import { createMailer } from 'mailcraft-lite';
import path from 'path';

const mailer = createMailer({
  smtp: {
    host: 'smtp.example.com',
    port: 587,
    secure: false,
    auth: {
      user: 'username',
      pass: 'password'
    }
  },
  from: '[email protected]',
  templateDir: path.join(__dirname, 'emails')
});

Advanced Configuration (Custom Renderer)

const mailer = createMailer({
  smtp: {
    host: 'smtp.example.com',
    port: 465,
    secure: true,
    auth: {
      user: 'username',
      pass: 'password'
    }
  },
  from: '[email protected]',
  templateDir: './templates',
  render: (template: string, data: Record<string, unknown>) => {
    return customRender(template, data);
  }
});

Sending Emails

Basic Email

await mailer.send({
  to: '[email protected]',
  subject: 'Hello World',
  template: '<h1>Hello {{name}}!</h1>',
  data: { name: 'John' }
});

With Attachments

await mailer.send({
  to: ['[email protected]', '[email protected]'],
  cc: '[email protected]',
  subject: 'Monthly Report',
  templateName: 'report.html',
  data: {
    month: 'January',
    revenue: 50000
  },
  attachments: [
    { filename: 'report.pdf', path: '/path/to/report.pdf' },
    { filename: 'data.csv', path: '/path/to/data.csv' }
  ]
});

Template Sources

• template → direct string
• templateName → relative to templateDir
• templatePath → absolute path

Exactly one must be provided.

Templates

Use {{variable}} placeholders.

All values are:

• Automatically HTML escaped
• CSS inlined

Example:

<h1>Welcome, {{name}}!</h1>
<p>Your code is <strong>{{code}}</strong></p>

API Reference

createMailer(options: MailerOptions)

Creates a new mailer instance.

MailerOptions

| Option | Type | Required | Description | |------------- |----------- |--------- |------------------------- | | smtp | SMTPConfig | Yes | SMTP server config | | from | string | No | Default sender | | templateDir | string | No | Base template directory | | render | Function | No | Custom renderer |

send(options: SendMailOptions)

Returns Promise<SentMessageInfo>.

| Option | Type | Required | |---------------------------------------|-------------------------------|----------| | to | string | string[] | Yes | | subject | string | Yes | | template | string | Yes* | | templateName | string | Yes* | | templatePath | string | Yes* | | data | Record<string, unknown> | No | | cc | string | string[] | No | | bcc | string | string[] | No | | attachments | Attachment[] | No |

Security

• Path traversal protection
• Automatic XSS prevention
• No eval() usage
• Type-safe API

Best Practices

• Use environment variables for SMTP credentials
• Keep templates isolated
• Wrap send() calls in try/catch
• Add rate limiting for bulk emails