@zyther/tzmail is a TypeScript/Node.js library for generating templates and sending messages via SMTP, SendGrid, Amazon SES, or Mailgun. It includes ready-made themes, basic validation, bounded caching, attachments, and independent provider factories.
Scope: tzmail is a templates, transports, and sending queue layer, not a complete campaign platform. For high volume, use a durable queue, define idempotency and retries, and coordinate limits with the provider. SMTP or an API accepting the message does not guarantee inbox delivery.
tzmail is released under the ISC License.
- Node.js 20 or later.
nodemailer6.9, 7, or 8, installed as a peer dependency.- To use Amazon SES, also install the optional peer
@aws-sdk/client-sesv2; SendGrid and Mailgun use Node's nativefetchand do not need the vendor SDKs. - To use the asynchronous queue, install the optional peer
bullmqand provide a compatible Redis instance.
npm install @zyther/tzmail nodemailer
# Optional, only if using the queue:
npm install bullmqUse environment variables or a secret manager for credentials; do not store SMTP passwords in source code.
import {
EmailFactory,
ThemeType,
type IEmailConfig,
type ITemplateConfig
} from '@zyther/tzmail';
const smtp: IEmailConfig = {
host: process.env.SMTP_HOST!,
port: Number(process.env.SMTP_PORT ?? 587),
secure: false, // Implicit TLS usually uses 465; 587 usually negotiates STARTTLS
auth: {
user: process.env.SMTP_USER!,
pass: process.env.SMTP_PASSWORD!
},
defaultFrom: 'Acme <noreply@example.com>'
};
// create() is suitable for services/tenants with isolated configurations.
const mailer = EmailFactory.create(smtp);
const templateConfig: ITemplateConfig = {
header: { show: true, logo: { type: 'text', text: 'Acme' } },
body: {
title: 'Welcome!',
message: 'Your account is ready.',
buttonText: 'Open account',
buttonUrl: 'https://example.com/account'
},
footer: { show: true, unsubscribeText: 'Unsubscribe' }
};
const template = mailer.getTemplateService().createTemplate(
ThemeType.MODERN,
'light',
templateConfig
);
const result = await mailer.sendEmail({
to: 'person@example.com',
subject: 'Your account is ready',
template
});
if (result.status !== 'success') {
// Log operational metadata according to the application's policy.
// Avoid sending message bodies, credentials, or personal data to logs.
console.error('Email send failed', result.status, result.errorStage);
}
// During graceful process/worker shutdown:
mailer.close();IEmailConfig exposes the main SMTP and Nodemailer pool options. pool, maxConnections, maxMessages, rateDelta, and rateLimit control the pool and sending rate for a single instance/process:
const smtp: IEmailConfig = {
host: process.env.SMTP_HOST!,
port: 587,
secure: false,
auth: { user: process.env.SMTP_USER!, pass: process.env.SMTP_PASSWORD! },
defaultFrom: 'Acme <noreply@example.com>',
pool: true,
maxConnections: 5,
maxMessages: 100,
rateDelta: 1_000,
rateLimit: 50,
connectionTimeout: 30_000,
greetingTimeout: 30_000,
socketTimeout: 60_000
};
const mailer = EmailFactory.create(smtp);
await mailer.verifyTransport(); // validates the connection/credentials; does not send emailauth supports login credentials (username/password), oauth2 credentials (for example, user, clientId, clientSecret, refreshToken, or accessToken), and Nodemailer's custom mechanism. Store tokens, callbacks, and secrets in a secret manager; the password example above is not required for OAuth2.
Choose limits according to your SMTP provider. Adding replicas multiplies connections and local limits; apply distributed control/a queue and quotas in the system that coordinates the workers.
EmailFactory.create(config, templateOptions?, attachmentOptions?) creates an isolated instance. EmailFactory.initialize(...)/getInstance() remain available for a process-wide singleton; a second initialization with different settings throws an error instead of silently reusing the first SMTP configuration. Close each created instance with close() during shutdown.
BullMQ is an optional peer. Install it and configure Redis before creating the queue. Producer processes only need to add jobs; run startWorker() in dedicated workers and use the same queueName, prefix, and Redis connection. Workers can be scaled horizontally. concurrency controls simultaneous jobs per worker, while limiter applies a shared per-queue rate across BullMQ workers.
import { EmailFactory, type IEmailConfig } from '@zyther/tzmail';
const queue = EmailFactory.createBullMQQueue({
connection: {
host: process.env.REDIS_HOST!,
port: Number(process.env.REDIS_PORT ?? 6379),
password: process.env.REDIS_PASSWORD,
tls: process.env.REDIS_TLS === 'true' ? {} : undefined
},
queueName: 'transactional-email',
concurrency: 10,
limiter: { max: 100, duration: 1_000 },
// BullMQ data points per minute: 14 days = 14 * 24 * 60 points.
workerMetrics: { maxDataPoints: 20_160 },
defaultJobOptions: {
attempts: 5,
backoff: { type: 'exponential', delay: 1_000, jitter: 0.2 }
}
});
// Producer/API process:
const job = await queue.enqueueEmail({
to: 'ana@example.com',
subject: 'Receipt',
text: 'Payment confirmed.'
}, { idempotencyKey: 'receipt-order-123' });
console.log('Job ID:', job.id);
// Or enqueue a batch, sent to Redis via addBulk:
await queue.enqueueBulk([
{ email: { to: 'a@example.com', subject: 'Hello', text: 'A' }, job: { idempotencyKey: 'batch-a' } },
{ email: { to: 'b@example.com', subject: 'Hello', text: 'B' }, job: { idempotencyKey: 'batch-b' } }
]);Expose exportPrometheusMetrics() on an internal /metrics endpoint; it returns the text format expected by Prometheus and can accept low-cardinality global labels:
import { createServer } from 'node:http';
const metricsServer = createServer(async (req, res) => {
if (req.method !== 'GET' || req.url !== '/metrics') {
res.writeHead(404).end();
return;
}
try {
const body = await queue.exportPrometheusMetrics({
env: process.env.NODE_ENV ?? 'production',
service: 'tzmail'
});
res.writeHead(200, {
'content-type': 'text/plain; version=0.0.4; charset=utf-8',
'content-length': String(Buffer.byteLength(body))
});
res.end(body);
} catch {
res.writeHead(500).end('Metrics unavailable');
}
});
metricsServer.listen(9464, '0.0.0.0');Configure Prometheus to scrape mail-metrics:9464 every 15 seconds. A dedicated exporter per queue avoids duplicate count series when multiple replicas query the same Redis instance. In Grafana, create dashboards for waiting, active, and failed jobs, and alerts for growing backlogs/failures. Do not use email addresses, job IDs, or other unbounded values as labels.
In a worker process, create the transport as usual and start the consumer with the same queue configuration:
const mailer = EmailFactory.createSendGrid({
apiKey: process.env.SENDGRID_API_KEY!,
defaultFrom: 'Acme <noreply@example.com>'
});
queue.startWorker(mailer, { concurrency: 20 }); // inherits workerMetrics from the configuration
// Global events from all workers; use them for real-time logging/alerts.
const events = queue.createQueueEvents();
events.on('completed', ({ jobId }) => logger.info({ jobId }, 'email job completed'));
events.on('failed', ({ jobId, failedReason }) => logger.error({ jobId, failedReason }, 'email job failed'));
// During graceful shutdown, wait for active jobs before closing the transport:
await queue.close();
mailer.close();enqueueEmail() accepts idempotencyKey to deduplicate jobs while the previous job is still retained in the queue; the key is transformed into a Redis ID without exposing the original value. Jobs removed after completion/failure are no longer deduplicated. enqueueBulk() accepts up to 1,000 messages by default; a partial failure during bulk insertion may leave some jobs enqueued, so use idempotency keys and check the queue before retrying the batch. getJobCounts() returns counts of waiting, active, completed, failed, delayed, and paused jobs. getMetrics('completed' | 'failed') reads throughput series in one-minute intervals stored in Redis; all workers in the queue must use the same workerMetrics.maxDataPoints.
The default options are 5 attempts, exponential backoff with jitter, retention of completed jobs for up to 24 hours/10,000 items, and failed jobs for up to 7 days/50,000 items. These can be changed in defaultJobOptions or per job. BullMQ retries worker failures; a transport failure after remote acceptance but before the response can therefore duplicate a send. Job idempotency prevents duplicate enqueueing while a job is retained, but does not provide exactly-once delivery by the provider. Validation/rendering errors and partial deliveries are marked as unrecoverable. Partial deliveries are not retried automatically, to avoid resending to recipients who have already been accepted; review these failed jobs and handle rejected recipients through a dedicated flow.
The template is rendered before entering the queue, to avoid serializing closures/functions. Buffer content is converted to Base64 and stored in Redis. Attachment path remains a local path that must be accessible to all workers. The default maximum serialized size is 10 MiB per job (maxPayloadBytes); increase it cautiously, since large attachments consume Redis and memory. The payload contains email addresses and content: protect Redis with TLS, authentication, network controls, and appropriate retention. close() waits for active workers and closes the queue; call it during graceful shutdown.
See also the official BullMQ documentation on retries and backoff, job IDs, bulk insertion, rate limiting, and graceful worker shutdown.
Provider factories create independent instances, so you can, for example, maintain a transactional sender through SES and a marketing sender through SendGrid in the same process. There is no shared singleton state across keys or tenants.
The adapter uses the official v3 API via fetch (it does not require @sendgrid/mail). The sender must be verified in SendGrid. API attachments are Base64-encoded and held in memory during the call; configure maxAttachmentBytes to limit the size of each file.
const sendgrid = EmailFactory.createSendGrid({
apiKey: process.env.SENDGRID_API_KEY!,
defaultFrom: 'Acme <noreply@example.com>',
requestTimeoutMs: 30_000,
maxAttachmentBytes: 10 * 1024 * 1024
});
const result = await sendgrid.sendEmail({
to: ['ana@example.com', 'bruno@example.com'],
subject: 'Account update',
text: 'Your account has been updated.'
});
sendgrid.close();Use apiUrl if the account is configured for a regional endpoint. The default is https://api.sendgrid.com. References: Mail Send API and attachments in the official SDK.
The adapter uses the Messages API via fetch and multipart/form-data; it does not require mailgun.js. Set the sending domain and account region. apiUrl should only be customized for a custom or controlled endpoint.
const mailgun = EmailFactory.createMailgun({
apiKey: process.env.MAILGUN_API_KEY!,
domain: process.env.MAILGUN_DOMAIN!,
region: 'eu', // omit or use 'us' for the US API
defaultFrom: 'Acme <noreply@example.com>',
requestTimeoutMs: 30_000,
maxAttachmentBytes: 10 * 1024 * 1024
});
await mailgun.sendEmail({
to: 'ana@example.com',
subject: 'Hello',
html: '<p>Message sent via Mailgun.</p>'
});
mailgun.close();The adapter uses https://api.mailgun.net in the US and https://api.eu.mailgun.net for region: 'eu'. Attachments are prepared in memory before the POST; set an appropriate limit. For inline images, Mailgun derives the Content-ID from the file name; when cid is provided, the adapter converts cid:<value> references in the HTML to cid:<filename>. See the official Messages API.
Install the official SDK only if you are going to use SES:
npm install @aws-sdk/client-sesv2const ses = EmailFactory.createSES({
region: process.env.AWS_REGION ?? 'us-east-1',
defaultFrom: 'Acme <noreply@example.com>'
// Without explicit credentials, the AWS SDK uses the default credential chain,
// such as an IAM role, environment variables, or local credentials.
});
await ses.sendEmail({
to: 'ana@example.com',
subject: 'Receipt',
text: 'Payment confirmed.'
});
ses.close();The adapter uses Nodemailer's SESv2 transport. The sender identity must be verified and the role/credential must have the ses:SendEmail permission. The SES transport does not enforce rate limits on its own; use the BullMQ queue or your own coordination to respect the account quota. Nodemailer documents that the SES transport builds the full message in memory, including attachments. See SES transport and AWS SDK credentials.
EmailFactory.createWithTransport(transport, defaultFrom?, templateOptions?, attachmentOptions?) lets you connect a custom adapter that implements IEmailTransport. verifyTransport() works when the transport offers a non-destructive check; SendGrid and Mailgun do not send test requests because the sending API does not provide a safe health check with minimal permissions. For these providers, validate the key and permissions in the deployment environment and monitor actual send responses.
All factories accept the same optional template and attachment options. The default requestTimeoutMs for the SendGrid and Mailgun APIs is 30 seconds. maxAttachmentBytes is optional and limits each individual attachment; SendGrid/Mailgun files and SES messages may be buffered in memory. For large files, use conservative limits and SMTP transport when appropriate.
The library includes 34 themes, each with light and dark variants. The original options are ThemeType.MODERN, CORPORATE, MINIMAL, MONOKAI, and SYSTEM; additional palettes are also available:
| Theme | Style |
|---|---|
AURORA |
Cool teal and violet, inspired by the northern lights. |
OCEAN |
Calm navy, marine blue, and cyan. |
SUNSET |
Warm coral, terracotta, amber, and plum. |
LAVENDER |
Elegant violet and rose accents on soft surfaces. |
FOREST |
Evergreen, moss, sage, and warm cream. |
EDITORIAL |
Serif-led magazine styling with warm paper and ink tones. |
PASTEL |
Friendly peach, mint, and lavender accents with readable contrast. |
NEOBRUTAL |
Bold black and white with electric yellow and cobalt accents. |
GLASS |
Cool blue-gray colors on solid, email-client-friendly surfaces. |
MIDNIGHT |
Premium midnight navy with champagne-gold accents. |
SAAS |
Crisp indigo product-update layout with system fonts. |
CITRUS |
Warm orange editorial palette for announcements and launches. |
BERRY |
Polished berry palette with a rounded, community-friendly CTA. |
PAPER |
Editorial newsletter layout with warm paper surfaces. |
NEON |
Technical high-contrast layout with teal energy. |
ALPINE |
Fresh natural layout with rounded green surfaces. |
ORBIT |
Precise violet product layout with a compact rhythm. |
LINEN |
Quiet editorial layout with warm neutral surfaces. |
BLOOM |
Delicate berry layout for launches and community notes. |
SLATE |
Sober modular layout for modern corporate communication. |
MARIGOLD |
Warm editorial layout with restrained amber accents. |
INKWELL |
Literary black-and-white layout with a measured rhythm. |
TIDE |
Open marine layout with calm teal surfaces. |
CLAY |
Warm crafted layout with soft terracotta framing. |
CLOUD |
Light product layout with airy blue surfaces. |
CAMPUS |
Academic editorial layout with formal typography. |
NOIR |
Minimal premium layout with controlled monochrome contrast. |
MINT |
Fresh rounded layout for calm product and community updates. |
SAFFRON |
Bright product-editorial layout with orange and gold accents. |
All themes use fluid, table-based email markup. On screens up to 600px wide, calls to action expand to the available width and footer links stack vertically. Use TemplateFactory.listThemes() to enumerate available themes and TemplateFactory.getThemeInfo(theme) to read each theme's description and features.
The standalone interactive theme gallery compares all 34 themes in light and dark appearances using the same English sample content. Browse full email layouts, search by theme or layout, and open desktop or mobile previews.
Choose a theme for its complete visual style: each theme coordinates the header, body, button, footer, colors, type, and spacing. Theme defaults provide deliberate section alignment. Override it with header.alignment, body.alignment, or footer.alignment (left, center, or right). The CTA follows body alignment unless body.buttonAlignment is explicit.
const html = await mailer.getTemplateService().previewTemplate(
ThemeType.EDITORIAL,
'light',
{
header: { show: true, logo: { type: 'text', text: 'Field Notes' } },
body: {
title: 'A more thoughtful arrival.',
message: 'Give the idea room, the message clarity, and the next step a clear purpose.',
buttonText: 'Explore what comes next',
buttonUrl: 'https://example.com/updates',
alignment: 'left'
},
footer: {
show: true,
links: [{ text: 'Preferences', url: 'https://example.com/preferences' }],
unsubscribeText: 'Unsubscribe',
unsubscribeUrl: 'https://example.com/unsubscribe'
}
}
);Logo and hero images are optional; every theme has a complete text-first layout. Section backgroundColor and textColor overrides are supported. When a requested color would be hard to read against its background, the renderer selects a more legible foreground. Footer links are unlined by default; use linkDecoration: 'underline' to underline footer navigation and unsubscribe links consistently.
The footer recognizes 44 platforms: facebook, twitter, x, linkedin, github, instagram, youtube, tiktok, pinterest, reddit, gitlab, stackoverflow, medium, dribbble, behance, telegram, threads, bluesky, mastodon, whatsapp, discord, slack, snapchat, twitch, spotify, soundcloud, vimeo, tumblr, flickr, vk, wechat, line, signal, quora, producthunt, devto, hashnode, substack, patreon, buymeacoffee, kofi, wordpress, blogger, and rss.
Social badges default to icon-only display and are rendered inline as email-safe, colored typographic marks—no external icon image or CDN is required. The accessible platform name remains on each link, so it does not turn into a broken-image alt label when a recipient's email client blocks remote images. Set footer.socialLinkDisplay to 'icon-and-name' to show the platform names alongside the icons.
footer: {
show: true,
socialLinkDisplay: 'icon-and-name',
socialLinks: [
{ platform: 'bluesky', url: 'https://bsky.app/profile/example.com' },
{ platform: 'instagram', url: 'https://instagram.com/example' },
{ platform: 'github', url: 'https://github.com/example' }
]
}The SocialPlatform type is exported for TypeScript consumers. URLs must be absolute http: or https: links.
See the theme gallery and customization guide for tips on previewing, choosing, and customizing themes.
Templates also support language (default en), direction (ltr, rtl, or auto; default ltr), and a hidden preheader (up to 500 printable characters) for inbox previews. Preheaders support the same escaped per-recipient placeholders as other text fields.
const html = await mailer.getTemplateService().previewTemplate(
ThemeType.MIDNIGHT,
'dark',
{
language: 'en',
direction: 'ltr',
preheader: 'Hello, {{user.firstName}} — your account update is ready.',
body: { title: 'Welcome, {{user.firstName}}', message: 'Your update is available.' }
},
{ templateData: { user: { firstName: 'Sam' } } }
);const service = mailer.getTemplateService();
const html = await service.previewTemplate(
ThemeType.CORPORATE,
'light',
{
header: { show: true, logo: { type: 'text', text: 'Acme' } },
body: { title: 'Hello, Ana', message: 'See what is new.' },
footer: {
show: true,
links: [{ text: 'Privacy', url: 'https://example.com/privacy' }],
unsubscribeText: 'Unsubscribe',
unsubscribeUrl: 'https://example.com/unsubscribe?token=...'
}
},
{}
);Headers can also use an image logo and a full-width hero image. URLs must use http: or https:, and remote images should be hosted on a trusted domain:
const template = service.createTemplate(ThemeType.PAPER, 'light', {
header: {
show: true,
logo: {
type: 'image',
imageUrl: 'https://cdn.example.com/brand/logo.png',
alt: 'Acme'
},
heroImageUrl: 'https://cdn.example.com/campaign/spring.jpg',
heroAlt: 'Spring collection'
},
body: {
alignment: 'left',
buttonAlignment: 'right',
title: 'A new season is here',
message: 'Explore the latest collection.'
}
});ITemplateServiceOptions options include:
| Option | Default | Description |
|---|---|---|
cache |
true |
In-memory cache by configuration. Can be disabled per call with { cache: false }. |
cacheTTL |
3600 |
TTL in seconds; 0 disables storage. |
maxCacheEntries |
100 |
Positive limit on cached entries; approximate LRU eviction. |
maxHistoryEntries |
100 |
Limit on IDs in the history. |
maxVersionsPerTemplate |
10 |
Versions retained per template. |
validateConfig |
true |
Validates template options before rendering. |
import { TemplateService } from '@zyther/tzmail';
const service = new TemplateService({
cache: true,
cacheTTL: 900,
maxCacheEntries: 500,
maxHistoryEntries: 200
});The cache and history are local to the process, not distributed. Call service.dispose() when you create TemplateService directly and no longer need it. EmailFactory.close() stops the associated service timer.
getTemplateStats() returns totalTemplates, cachedTemplates, totalHits, cacheRequests, cacheHitRate, and counts by theme; requests that bypass/disable the cache are not included in the hit rate.
title,message, logo name, button/link/footer text, and textual metadata are escaped by the renderer.body.contentandbody.htmlare treated as trusted HTML to allow custom markup.body.htmlis the explicit, readable alias;contentremains supported for compatibility. Do not pass user-provided HTML without sanitizing it with a policy appropriate to the application.TemplateBuilder.buildBody()is a low-level API and also expects trusted HTML; preferTemplateServicefor validation and interpolation.IEmailOptions.htmlis also passed through as HTML supplied by the caller; treat it as trusted content or sanitize it before sending.- Action and link URLs accept absolute
https:,http:, ormailto:URLs; images/logos and social links accepthttps:/http:. Schemes such asjavascript:anddata:and attributes containing injection characters are rejected. - Colors and some style values are validated. The library's validation does not replace business validation or sanitization of custom HTML.
For per-recipient customization, use {{placeholder}} in template text and pass templateData in the message. Nested keys are supported ({{user.firstName}}); leaf values must be primitives (string, number, boolean, or null), and a placeholder without a value causes rendering to fail instead of sending incomplete text. Values inserted into text are escaped; insertions into body.content are escaped before being added to the trusted HTML. Generated URL configuration fields (CTA, logo/hero images, footer links, social links and unsubscribe URL) are validated after interpolation. URL-valued placeholders inside explicitly trusted body.content/body.html remain the caller's validation responsibility; HTML escaping is not URL-scheme validation.
await mailer.sendEmail({
to: 'ana@example.com',
subject: 'Welcome',
template,
templateData: {
user: { firstName: 'Ana' },
accountId: 'acct-123',
actionUrl: 'https://example.com/account/acct-123'
}
});For example, use title: 'Hello, {{user.firstName}}' and buttonUrl: '{{actionUrl}}' in the template configuration. The dynamic URL must still comply with the allowed schemes.
Attachments specified by path remain as paths so Nodemailer can stream them without loading entire large files into memory. In production, prefer restricting the allowed root and enforcing a size limit:
const mailer = EmailFactory.create(
smtp,
{ cache: true, cacheTTL: 900 },
{ allowedRoot: '/srv/app/mail-attachments', maxSizeBytes: 10 * 1024 * 1024 }
);
const attachment = await mailer.getAttachmentService().addFromPath(
'/srv/app/mail-attachments/report.pdf'
);
await mailer.sendEmail({
to: 'finance@example.com',
subject: 'Report',
text: 'Please find the report attached.',
attachments: [attachment]
});allowedRoot resolves real paths and rejects paths outside the root, including symlink escapes at validation time. Keep the root and its directories unwritable by untrusted users to reduce the risk of the file being swapped between validation and reading. If it is not set, the application is responsible for ensuring that paths are trusted. maxSizeBytes is optional; buffer attachments are also checked. addFromUrl() does not download URLs and remains unimplemented.
sendEmail() always returns an IEmailSendResult; validation, rendering, and transport are identified by errorStage:
type IEmailSendResult = {
success: boolean;
status: 'success' | 'partial' | 'failure';
messageId?: string;
response?: string;
accepted?: Array<string | { address: string; name: string }>;
rejected?: Array<string | { address: string; name: string }>;
error?: unknown;
errorStage?: 'validation' | 'render' | 'smtp' | 'provider';
};success is true only when the transport reports no rejected recipients. partial means partial acceptance and rejection; route these cases to explicit handling/retry in the application. An API or server accepting the message does not prove final delivery, that it was read, or that it avoided spam.
- Use
BullMQEmailQueueor another durable queue/outbox with workers, idempotency, and retries with backoff; do not automatically retry sends without a duplicate-prevention strategy. - Configure SPF, DKIM, DMARC, sending domain/reputation, quotas, and bounce/unsubscribe handling with the provider and in the application.
- Keep secrets out of the repository and rotate them; do not log message content or link tokens.
- Size
maxConnections/rateLimitaccording to the provider and the number of replicas. Nodemailer pool limits are local; the BullMQ limiter is shared by the queue. - Monitor
status,errorStage,accepted/rejected, latency, and queues with redacted logs and custom metrics.