MailForge SDK

A next-generation client-side email SDK — better than EmailJS in every way.

Zero dependencies · Multi-provider · Powerful templates · Queue & retry · Plugin system · Batch send · Analytics

Install

npm install @pariharshyamu/mailforge

Or via CDN:

<script src="https://unpkg.com/@pariharshyamu/mailforge/mailforge.js"></script>

Quick Start

const MailForge = require('@pariharshyamu/mailforge');
// or: import MailForge from '@pariharshyamu/mailforge';

MailForge.init('resend', {
  apiKey: 're_your_api_key',
  defaultFrom: '[email protected]'
});

await MailForge.send({
  to: '[email protected]',
  subject: 'Welcome aboard!',
  html: '<h1>Hello!</h1><p>Thanks for signing up.</p>'
});

Why MailForge over EmailJS?

| Feature | EmailJS | MailForge | |---|---|---| | Client-side email sending | ✓ | ✓ | | Template variables | ✓ | ✓ | | Template conditionals ({{#if}}) | ✗ | ✓ | | Template loops ({{#each}}) | ✗ | ✓ | | Template filters & pipes | ✗ | ✓ | | Multiple providers (Resend, SendGrid, Mailgun) | ✗ | ✓ | | Custom provider API | ✗ | ✓ | | Queue with offline support | ✗ | ✓ | | Auto-retry with backoff | ✗ | ✓ | | Rate limiting | ✗ | ✓ | | Batch send | ✗ | ✓ | | CC, BCC, Reply-To | Partial | ✓ | | Email validation | ✗ | ✓ | | Plugin system | ✗ | ✓ | | Event system (on/off/emit) | ✗ | ✓ | | Multiple isolated instances | ✗ | ✓ | | Analytics & stats | ✗ | ✓ | | Zero dependencies | ✓ | ✓ |

Providers

| Provider | Key | Config | |---|---|---| | Resend | 'resend' | { apiKey } | | SendGrid | 'sendgrid' | { apiKey } | | Mailgun | 'mailgun' | { apiKey, domain } | | EmailJS | 'emailjs' | { serviceId, publicKey } | | Generic REST | 'generic' | { endpoint, headers } | | Custom | registerProvider() | Any |

Template Engine

MailForge.defineTemplate('order-confirm', {
  subject: 'Order #{{ orderId }} confirmed, {{ name | capitalize }}!',
  html: `
    <h1>Thanks, {{ name | capitalize }}!</h1>
    {{#if isPremium}}<p>🌟 Free shipping!</p>{{/if}}
    <ul>
    {{#each items}}
      <li>{{ this.name }} × {{ this.qty }} — {{ this.price | currency }}</li>
    {{/each}}
    </ul>
    <p><strong>Total: {{ total | currency }}</strong></p>
  `
});

await MailForge.send({
  to: '[email protected]',
  templateId: 'order-confirm',
  templateParams: { orderId: 'A1042', name: 'jane doe', isPremium: true, items: [...], total: 249.97 }
});

Built-in Filters

upper · lower · capitalize · trim · escape · json · date · time · currency · truncate · default

Queue & Retry

MailForge.init('sendgrid', {
  apiKey: 'SG.your_key',
  queueEnabled: true,
  persistQueue: true,      // survives page refresh via localStorage
  retryAttempts: 5,
  retryDelay: 2000,
  rateLimit: { maxCalls: 10, windowMs: 1000 }
});

Batch Send

const results = await MailForge.sendBatch(
  ['[email protected]', '[email protected]'],
  { templateId: 'newsletter' },
  (email, i) => ({ email, edition: 42 })
);

Plugin System

const LoggerPlugin = {
  name: 'logger',
  install(forge) {
    forge.on('sending', ({ payload }) => console.log(`📤 ${payload.to}`));
    forge.on('sent', ({ result }) => console.log('✅', result));
    forge.on('failed', ({ error }) => console.error('❌', error));
  }
};

MailForge.use(LoggerPlugin);

Events

MailForge.on('init',    (data) => ...);
MailForge.on('sending', ({ payload, attempt }) => ...);
MailForge.on('sent',    ({ payload, result }) => ...);
MailForge.on('error',   ({ error, attempt }) => ...);
MailForge.on('failed',  ({ error, payload }) => ...);
MailForge.on('queued',  ({ jobId, payload }) => ...);
MailForge.on('queue:sent',   ({ jobId, result }) => ...);
MailForge.on('queue:failed', ({ jobId }) => ...);

API Reference

MailForge.init(provider, config) — Initialize with a provider

MailForge.send(options) — Send an email (returns Promise)

MailForge.sendBatch(recipients, options, varsFn) — Send to multiple recipients

MailForge.defineTemplate(id, template) — Define a named template

MailForge.removeTemplate(id) — Remove a template

MailForge.addTemplateFilter(name, fn) — Register a custom filter

MailForge.registerProvider(name, provider) — Register a custom provider

MailForge.use(plugin) — Install a plugin

MailForge.validateEmail(email) — Validate an email address

MailForge.renderTemplate(templateOrId, vars) — Render a template

MailForge.getStats() — Get analytics stats

MailForge.create() — Create a new isolated instance

MailForge.on(event, listener) — Listen to events

MailForge.off(event, listener) — Remove a listener

MailForge.version — SDK version string

License

Proprietary — © 2024 Shyamu Parihar. All rights reserved.