TECHNICAL SPECIFICATIONS v3.6.0

DOCUMENTATION

Comprehensive guide for low-latency, resilient email delivery infrastructure. Built for scale, engineered for reliability.

/ Installation

Install Senderwolf via npm. The engine includes built-in TypeScript definitions.

bash

npm install senderwolf

TypeScript Support

Senderwolf is built with TypeScript and includes built-in type definitions. Using TypeScript provides IntelliSense support and compile-time error checking for all configurations.

/ Quick Start

The fastest way to send an email is using a provider-specific function.

javascript

import { sendGmail } from "senderwolf";

await sendGmail(
  "your-email@gmail.com",
  "your-app-password",
  "recipient@example.com",
  "Hello from Senderwolf",
  "<h1>Message content</h1>"
);

/ One-Liner Sending

Senderwolf provides utility functions for quick sending without extensive configuration.

Auto-Detection

The sendEmail function can automatically detect provider settings based on the authentication address.

javascript

import { sendEmail } from "senderwolf";

await sendEmail({
  smtp: {
    auth: { user: "example@outlook.com", pass: "password" }
  },
  mail: {
    to: "recipient@example.com",
    subject: "Auto-detected Settings",
    html: "<p>Senderwolf detected the Outlook SMTP settings.</p>"
  }
});

/ High-Performance Mailer

For high-volume applications, use the Mailer instance generated by createMailer.

javascript

import { createMailer } from "senderwolf";

const mailer = createMailer({
  smtp: {
    provider: "gmail",
    auth: { user: "your@gmail.com", pass: "app-password" }
  },
  defaults: {
    fromName: "My Application",
    replyTo: "support@example.com"
  }
});

await mailer.sendHtml("user@example.com", "Subject", "<h1>Content</h1>");

/ Connection Pooling

Senderwolf includes a sophisticated connection pooling system that can improve bulk sending performance by 50-80%.

javascript

const mailer = createMailer({
  smtp: {
    pool: {
      maxConnections: 5,
      maxMessages: 100,
      rateDelta: 1000,
      rateLimit: 3,
      idleTimeout: 30000
    }
  }
});

/ Template System

Handlebars-like template engine with support for variables, logic, and loops.

javascript

await mailer.sendTemplate("welcome", "user@example.com", {
  appName: "Senderwolf App",
  userName: "John Doe"
});

Template Syntax

Variables: {{name}}
Nested: {{user.root}}
Loops: {{#each array}}
If/Unless Logic

/ DKIM Signing

Improve deliverability and prevent spoofing by signing your emails with RFC 6376-compliant signatures.

javascript

await sendEmail({
  smtp: {
    dkim: {
      domainName: "example.com",
      keySelector: "mail",
      privateKey: PEM_STRING_OR_PATH
    }
  }
});

/ CLI Tooling

Senderwolf includes two command-line tools: senderwolf and senderwolf-templates.

SENDERWOLF CLI

Interactive prompt, test connections, and dry-run previews.

TEMPLATES CLI

Preview, create, and validate templates in the terminal.

/ Configuration & Providers

Supports 13+ providers out of the box, including Gmail, Outlook, SendGrid, and Amazon SES.

json

{
  "provider": "gmail",
  "user": "your@gmail.com",
  "pass": "app-password"
}

/ Error Handling

Granular error handling using custom classes and lifecycle events.

javascript

mailer.on("sending", (data) => console.log("Sending..."));
mailer.on("sent", (info) => console.log("Success"));
mailer.on("failed", (err) => console.error("Failed"));

/ Advanced Features

SYSTEM CAPABILITIES

ATTACHMENTS: Path, Buffer, or String support.
EXPONENTIAL BACKOFF: Intelligent retry logic.
AUTO PLAIN-TEXT: Fallback generation from HTML.
CUSTOM HEADERS: Full SMTP header control.

/ Pluggable Logger

Inject any logger that implements the standard info, warn, error, and debug interface. Enable debug: true to surface info and debug messages.

Custom Object Logger

javascript

import { sendEmail } from "senderwolf";

const myLogger = {
  info:  (msg) => console.log(`[APP-INFO] ${msg}`),
  warn:  (msg) => console.warn(`[APP-WARN] ${msg}`),
  error: (msg) => console.error(`[APP-ERR] ${msg}`),
  debug: (msg) => console.debug(`[APP-DEBUG] ${msg}`)
};

await sendEmail({
  smtp: {
    provider: 'gmail',
    auth: { user: '...', pass: '...' },
    logger: myLogger,
    debug: true   // required to see info/debug output
  },
  mail: {
    to: 'user@example.com',
    subject: 'Logging Test',
    text: 'Check the console for custom log prefixes!'
  }
});

Using Winston

javascript

import winston from "winston";
import { createMailer } from "senderwolf";

const logger = winston.createLogger({
  level: 'info',
  transports: [new winston.transports.Console()]
});

const mailer = createMailer({
  smtp: {
    provider: 'gmail',
    auth: { user: '...', pass: '...' },
    logger
  }
});

/ Environment Variables

Configure Senderwolf entirely through environment variables — ideal for Docker, Kubernetes, and serverless deployments. When these variables are present, you can send emails with zero inline configuration.

Variable	Description
SENDERWOLF_SMTP_HOST	SMTP server host
SENDERWOLF_SMTP_PORT	SMTP server port
SENDERWOLF_SMTP_USER	SMTP username
SENDERWOLF_SMTP_PASS	SMTP password
SENDERWOLF_SMTP_SECURE	Set to true for TLS (port 465)
SENDERWOLF_FROM_EMAIL	Default sender email
SENDERWOLF_FROM_NAME	Default sender name
SENDERWOLF_DEBUG	Set to true to enable debug logging

javascript

import { sendEmail } from "senderwolf";

// SMTP settings are loaded from process.env automatically!
await sendEmail({
  mail: {
    to: 'recipient@example.com',
    subject: 'Zero Config!',
    text: 'Sent using environment variables.'
  }
});

/ Inline Images (CID)

Embed images directly into your HTML content using the cid (Content-ID) property on an attachment. The cid value must match the src attribute in your HTML exactly.

javascript

await sendEmail({
  smtp: { /* ... */ },
  mail: {
    to: 'user@example.com',
    subject: 'Check our logo!',
    html: '<h1>Welcome!</h1><img src="cid:unique-logo-id">',
    attachments: [
      {
        filename: 'logo.png',
        path: './assets/logo.png',
        cid: 'unique-logo-id'  // must match the src cid: value above
      }
    ]
  }
});

/ MIME Auto-Detection

Senderwolf automatically detects the MIME type of attachments based on the file extension. Specifying contentType is now optional for all common file formats.

javascript

await sendEmail({
  smtp: { /* ... */ },
  mail: {
    to: 'user@example.com',
    subject: 'Report Attached',
    text: 'See attached files.',
    attachments: [
      { filename: 'report.pdf',  path: './docs/report.pdf' },     // → application/pdf
      { filename: 'data.xlsx',   content: someBuffer },           // → spreadsheet
      { filename: 'styles.css',  content: 'body { color: red }' } // → text/css
    ]
  }
});

/ Scheduling & Delay

Schedule emails to be sent after a fixed delay or at a specific future time without any external infrastructure.

Fixed Delay (milliseconds)

javascript

await sendEmail({
  smtp: { /* ... */ },
  mail: {
    to: 'user@example.com',
    subject: 'Delayed Email',
    text: 'This was sent 5 seconds after the call.'
  },
  delay: 5000  // 5 000 ms = 5 seconds
});

Exact Time (Date)

javascript

const scheduledDate = new Date();
scheduledDate.setHours(scheduledDate.getHours() + 1); // 1 hour from now

await sendEmail({
  smtp: { /* ... */ },
  mail: {
    to: 'user@example.com',
    subject: 'Scheduled Email',
    text: 'This was scheduled for the future.'
  },
  sendAt: scheduledDate
});

NOTEScheduling is handled in-memory via setTimeout. If the Node.js process exits before the scheduled time, the email will not be sent. For persistent job queues, consider pairing Senderwolf with BullMQ or a similar task scheduler.