mail-time 3.0.0 → 4.0.0

package/README.md

@@ -1,81 +1,52 @@
-[![support](https://img.shields.io/badge/support-GitHub-white)](https://github.com/sponsors/dr-dimitru)
-[![support](https://img.shields.io/badge/support-PayPal-white)](https://paypal.me/veliovgroup)
-<a href="https://ostr.io/info/built-by-developers-for-developers?ref=github-mail-time-repo-top"><img src="https://ostr.io/apple-touch-icon-60x60.png" height="20"></a>
-<a href="https://meteor-files.com/?ref=github-mail-time-repo-top"><img src="https://meteor-files.com/apple-touch-icon-60x60.png" height="20"></a>
 
 # MailTime
 
-"Mail-Time" is NPM package for mail queue management. Build on top of the [`nodemailer`](https://github.com/nodemailer/nodemailer) package. Mail-Time made for single-server and horizontally scaled multi-server setups in mind.
-
-Every `MailTime` instance can have `type` configured as *Server* or *Client*. *Server* type of `MailTime` is great for creating an emailing micro-service app.
-
-The main difference between *Server* and *Client* `type` is that the *Server* handles the queue and __sends__ email. While the *Client* only __adds__ emails into the queue.
-
-## ToC
-
-- [How it works?](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#how-it-works)
-  - [With single SMTP](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#single-point-of-failure)
-  - [With multiple SMTP](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#multiple-smtp-providers)
-  - [For horizontally-scaled apps](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#sending-emails-from-cluster-of-servers)
-- [Features](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#features)
-- [Installation](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#installation)
-- [Meteor.js usage](https://github.com/veliovgroup/mail-time/blob/master/docs/meteor.md)
-- [Usage examples](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#basic-usage)
-  - [Require/Import `mail-time`](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#1-require-package)
-  - [Create NodeMailer's transports](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#2-create-nodemailers-transports)
-  - [Initiate `mail-time`](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#3-initiate-mail-time)
-    - [Connect to Redis](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#3a-initiate-and-connect-to-redis)
-    - [Connect to MongoDB](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#3b-initiate-and-connect-to-mongodb)
-    - [Initiate as *Client* instance](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#3c-optionally-create-client-type-of-mailtime)
-  - [Initiate two `MailTime` instances within the single app](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#two-mailtime-instances-usage-example)
-  - [Use templates](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#passing-variables-to-the-template)
-  - Different storage configurations:
-    - [Use MongoDB for queue and scheduler](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#using-mongodb-for-queue-and-scheduler)
-    - [Use MongoDB for queue and Redis for scheduler](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#using-mongodb-for-queue-and-redis-for-scheduler)
-    - [Use Redis for queue and MongoDB for scheduler](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#using-redis-for-queue-and-mongodb-for-scheduler)
-    - [Use Redis for queue and scheduler](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#using-redis-for-queue-and-scheduler)
-- [API](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#api)
-  - [`new MailTime` *Constructor*](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#new-mailtimeopts-constructor)
-  - [`new RedisQueue` *Constructor*](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#new-redisqueueopts-constructor)
-  - [`new MongoQueue` *Constructor*](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#new-mongoqueueopts-constructor)
-  - [`.sendMail()`](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#sendmailopts)
-  - [`.cancelMail()`](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#cancelmailuuid)
-  - [Default Template](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#static-mailtimetemplate)
-- [Custom Templates](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#template-example)
-- [Running tests](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#testing)
-
-## Main features:
-
-- 👨‍🔬 ~94% tests coverage;
-- 📦 Two simple dependencies, written from scratch for top performance;
-- 🏢 Synchronize email queue across multiple (horizontally scaled) servers;
-- 💪 Bulletproof design, built-in retries.
-
-## How does it work?
-
-Redundant solution for email transmission.
+[![npm version](https://img.shields.io/npm/v/mail-time.svg?label=mail-time)](https://www.npmjs.com/package/mail-time)
+[![CI](https://img.shields.io/github/actions/workflow/status/veliovgroup/mail-time/ci.yml?branch=master)](https://github.com/veliovgroup/mail-time/actions)
+[![license](https://img.shields.io/npm/l/mail-time.svg)](LICENSE)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/dr-dimitru?label=Sponsor)](https://github.com/sponsors/dr-dimitru)
+[![Donate](https://img.shields.io/badge/Donate-PayPal-00457C?logo=paypal&logoColor=white)](https://paypal.me/veliovgroup)
 
-### Single point of failure
+Bulletproof email queue for [horizontally scaled](#sending-emails-from-a-cluster) Node.js & Bun apps. Built on top of [`nodemailer`](https://github.com/nodemailer/nodemailer) and [`josk`](https://github.com/veliovgroup/josk). Single runtime dependency, ESM + CJS, full TypeScript declarations.
+
+`MailTime` runs in one of two modes:
+
+- **`server`** — drains the queue and sends emails via SMTP. The cluster-aware lease guarantees exactly one server sends each email even when many are running.
+- **`client`** — only enqueues emails. Use for app servers in a "dedicated mail micro-service" topology.
+
+Many clients + one or more servers coexist behind the same `prefix` in the same store.
+
+## Features
 
-Issue - mitigate a single point of failure via persistent queue and re-send attempts
+- 🏢 **Horizontally scaled** — synchronize one queue across N processes/hosts/DCs.
+- 🔁 **Multi-SMTP rotation** — `backup` (failover) and `balancer` (round-robin) strategies.
+- 💪 **Built-in retries** — storage-backed retry with per-letter transport pinning.
+- 🎯 **Per-recipient retries** — when a multi-`to` send is partially rejected, only the un-accepted addresses are retried; delivered ones never see a duplicate.
+- 📮 **Email concatenation** — fold same-`to` emails arriving inside a window into one letter.
+- 🎛️ **One-line setup** — built-in [presets](#settings-presets) for `transactional`, `otp`, `newsletter`, `marketing`, `notifications`, `alerts`.
+- 🛢️ **Three first-party storages** — MongoDB, Redis, PostgreSQL. Plus a [custom-adapter contract](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md).
+- 📦 **Bun ≥ 1.1.0 & Node ≥ 20.9.0** — same code, both runtimes.
+- 🤖 **Ships with AI agent skills** — see [AI agent skills](#ai-agent-skills) below.
+- 📐 **Hand-tuned ESM + CJS + TypeScript declarations**.
+- 🧪 **95%+ Jest coverage** (85% threshold enforced) + Mocha integration tests for every adapter.
+
+## How it works
+
+### Single point of failure
 
 ```ascii
 |----------------|         |------|         |------------------|
 |  Other mailer  | ------> | SMTP | ------> |  ^_^ Happy user  |
 |----------------|         |------|         |------------------|
 
-The scheme above will work as long as SMTP service is available
-or connection between your server and SMPT is up. Once network
-failure occurs or SMTP service is down - users won't be happy
+The scheme above works only as long as SMTP is up.
 
 |----------------|  \ /    |------|         |------------------|
 |  Other mailer  | --X---> | SMTP | ------> | 0_o Disappointed |
 |----------------|  / \    |------|         |------------------|
                      ^- email lost in vain
 
-Single SMTP solution may work in case of network or other failures
-As long as MailTime has not received confirmation what email is sent
-it will keep the letter in the queue and retry to send it again
+MailTime keeps every letter in the queue until SMTP confirms delivery.
 
 |----------------|    /    |------|         |------------------|
 |   Mail Time    | --X---> | SMTP | ------> |  ^_^ Happy user  |
@@ -87,7 +58,7 @@ it will keep the letter in the queue and retry to send it again
 
 ### Multiple SMTP providers
 
-Rotate email transports by using multiple SMTP providers. *MailTime* support two strategies `backup` (*rotate when failed*) and `balancer` (*round-robin rotation*)
+`backup` falls over on failure; `balancer` round-robins:
 
 ```ascii
                            |--------|
@@ -103,18 +74,14 @@ Rotate email transports by using multiple SMTP providers. *MailTime* support two
                            |--------|
 ```
 
-### Sending emails from cluster of servers
+### Sending emails from a cluster
 
-It is common to have horizontally scaled "Cluster" of servers for load-balancing and for durability.
-
-Most modern application has scheduled or recurring emails. For example, once a day — with recent news and updates. It won't be an issue with a single server setup — the server would send emails at a daily interval via timer or CRON. But in "Cluster" implementation — each server will attempt to send the same email. *MailTime* built to avoid sending the same email multiple times to a user from horizontally scaled applications.
-
-For the maximum durability and agility each Application Server can run *MailTime* in the "Server" mode:
+Most apps schedule recurring emails (daily digest, weekly summary). On a single server this is trivial. In a cluster, every node would otherwise send the same email N times. MailTime's lease prevents the duplicate sends.
 
 ```ascii
 |===================THE=CLUSTER===================| |=QUEUE=|
 | |----------|     |----------|     |----------|  | |       |   |--------|
-| |   App    |     |   App    |     |   App    |  | |       |-->| SMTP 1 |------\
+| | MailTime |     | MailTime |     | MailTime |  | |       |-->| SMTP 1 |------\
 | | Server 1 |     | Server 2 |     | Server 3 |  | |       |   |--------|       \
 | |-----\----|     |----\-----|     |----\-----|  | |       |                |-------------|
 |        \---------------\----------------\---------->      |   |--------|   |     ^_^     |
@@ -127,17 +94,17 @@ For the maximum durability and agility each Application Server can run *MailTime
 |=================================================| |=======|
 ```
 
-To split roles *MailTime* can run on a dedicated machine as micro-service. This case is great for private email servers with implemented authentication via rDNS and PTR records:
+For a dedicated mail machine (rDNS / PTR records), use `type: 'client'` on app servers and a single `type: 'server'` micro-service:
 
 ```ascii
 |===================THE=CLUSTER===================| |=QUEUE=| |===Mail=Time===|
 | |----------|     |----------|     |----------|  | |       | |               |   |--------|
-| |   App    |     |   App    |     |   App    |  | |       | | Micro-service |-->| SMTP 1 |------\
-| | Server 1 |     | Server 2 |     | Server 3 |  | |       | | running       |   |--------|       \
+| | MailTime |     | MailTime |     | MailTime |  | |       | | Micro-service |-->| SMTP 1 |------\
+| | Client 1 |     | Client 2 |     | Client 3 |  | |       | | running       |   |--------|       \
 | |-----\----|     |----\-----|     |----\-----|  | |       | | MailTime as   |                |-------------|
 |        \---------------\----------------\---------->      | | "Server" only |   |--------|   |     ^_^     |
 |                                                 | |       | | sending       |-->| SMTP 2 |-->| Happy users |
-| Each "App Server" runs MailTime as              | |       | | emails        |   |--------|   |-------------|
+| Each "App" runs MailTime as                     | |       | | emails        |   |--------|   |-------------|
 | a "Client" only placing emails to the queue.    | |    <--------            |                    /
 |                                                 | |    -------->            |   |--------|      /
 |                                                 | |       | |               |-->| SMTP 3 |-----/
@@ -145,666 +112,415 @@ To split roles *MailTime* can run on a dedicated machine as micro-service. This
 |=================================================| |=======| |===============|
 ```
 
-## Features
-
-- __Email Queue__ - Managed via MongoDB, Redis, or [Custom Queue](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md). Storage-based queue will survive server reboots and failures
-- __Made for horizontally scaled multi-server setups__ - *MailTime* is made to run in multi-server environments, like "Clusters", multiple app instances, load balanced solutions, and replications. *MailTime* is the perfect fit for applications scaled on a single machine, multiple virtual servers, multiple "bare metal" servers, within single or multiple data centers
-- __Email concatenation__ - Reduce amount of sent emails to a single user with concatenation, and avoid mistakenly duplicated emails. When "email concatenation" is enabled the same emails (*checked by addressee and content*) won't be sent twice. If emails are sent multiple times, due to issues in logic or application failures, - enable "email concatenation" to solve this behavior
-- __Multiple NodeMailer/SMTP transports__ — Support for multiple SMPT transports implemented in two modes - `backup` and `balancing`. Use this feature to reduce the cost of SMTP services and add extra layer of durability. When one of the transports is failing to send an email — `mail-time` will switch to the next one
-- __Sending retries__ — Built-in retries for failed to send emails due to network or other failures
-- __Templating__ — Built with support of [Mustache](https://mustache.github.io/)-like placeholders, see [templating docs](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#passing-variables-to-the-template)
+See [docs/multi-instance.md](https://github.com/veliovgroup/mail-time/blob/master/docs/multi-instance.md) and [docs/dedicated-mail-host.md](https://github.com/veliovgroup/mail-time/blob/master/docs/dedicated-mail-host.md) for full topologies.
 
 ## Installation
 
-To implement Server functionality — begin with installing `nodemailer`, although this package meant to be used with `nodemailer`, it's not added as the dependency, as `nodemailer` not needed by Client, and to give freedom to choose `nodemailer`'s version to fit every project needs:
+```sh
+npm install --save mail-time nodemailer
+# pick at least one storage driver:
+npm install --save redis        # for RedisQueue
+npm install --save mongodb      # for MongoQueue
+npm install --save pg           # for PostgresQueue
 
-```shell
-npm install --save nodemailer
+# Bun:
+bun add mail-time nodemailer
 ```
 
-Install *MailTime* package:
+> [!NOTE]
+> `nodemailer` and adapter drivers are peers (not bundled) so you can pin your own versions.
 
-```shell
-# for node@>=14.20.0
-npm install --save mail-time
+> [!IMPORTANT]
+> Upgrading from v3? See [Migration from 3.x](#migration-from-3x) and the full [v4.0.0 release notes](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v3-v4.md).
 
-# for node@<14.20.0
-npm install --save mail-time@=1.3.4
+For Meteor.js usage see [docs/meteor.md](https://github.com/veliovgroup/mail-time/blob/master/docs/meteor.md).
 
-# for node@<8.9.0
-npm install --save mail-time@=0.1.7
-```
+## AI agent skills
+
+MailTime ships a Claude / Copilot / Cursor / Codex / Gemini-ready skill bundle. Install it once in your project (or globally) and your AI agent will reach for the right preset, adapter, and pitfall list without you having to paste docs into the chat.
 
-## Basic usage
+```sh
+# Install the MailTime skill into the current project:
+npx skills add veliovgroup/mail-time
 
-Setup Nodemailer's transports, Queue storage, and *MailTime* instance
+# Recommended: also install the JoSk skill — MailTime is built on JoSk,
+# and deep scheduler questions resolve through JoSk's contract.
+npx skills add veliovgroup/josk
+```
 
-### Steps to get started
+The `npx skills` CLI ([vercel-labs/skills](https://github.com/vercel-labs/skills)) supports 50+ AI coding agents. Pass `-g` to install user-wide, or `-a claude-code` to target a specific agent. The bundled MailTime skill covers the public API, every queue adapter, the preset table, tuning levers, and common pitfalls — it's the same material as the README and `docs/`, structured for an LLM.
 
-See steps 1-4 below to learn about different parts of *MailTime* library and how it can get used. From configuration options to sending email
+## Quick start
 
-1. [Require `mail-time` package](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#1-require-package)
-2. [Create NodeMailer's transports](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#2-create-nodemailers-transports)
-3. [Initiate `mail-time` *server*](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#3-initiate-mail-time)
-   - a. [Connect to Redis](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#3a-initiate-and-connect-to-redis); Or
-   - b. [Connect to MongoDB](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#3b-initiate-and-connect-to-mongodb); And
-   - c. [*optionally*] [initiate `mail-time` as *client*](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#3c-optionally-create-client-type-of-mailtime)
-4. [Start sending emails](https://github.com/veliovgroup/mail-time?tab=readme-ov-file#4-send-email)
+Three things every MailTime needs: a connected storage **client**, one or more **nodemailer transports** (server only), and a **`josk.adapter`** that points at the scheduler storage (server only). Past that, reach for a [preset](#settings-presets) instead of hand-tuning every knob.
 
-#### 1. Require package
+### 1. Import
 
 ```js
-// import as ES Module
-import { MailTime, MongoQueue, RedisQueue } from 'mail-time';
+// ESM
+import { MailTime, MongoQueue, PostgresQueue, RedisQueue, mailTimePreset } from 'mail-time';
 
-// require as CommonJS
-const { MailTime, MongoQueue, RedisQueue } = require('mail-time');
+// CommonJS
+const { MailTime, MongoQueue, PostgresQueue, RedisQueue, mailTimePreset } = require('mail-time');
 ```
 
-#### 2. Create NodeMailer's transports
-
-For compatibility and flexibility *MailTime* has no dependency on `nodemailer` it should be installed and imported manually. Create one or more "SMTP transports" before initializing new *MailTime* instance.
+### 2. Create nodemailer transports
 
-For details and full list of options available in `.createTransport()` see [`nodemailer` docs](https://nodemailer.com/smtp/)
+Each transport must expose `.options` (set automatically by `nodemailer.createTransport({...})`). MailTime merges any `options.mailOptions` defaults onto every letter. To produce a `From:` header *from* a transport's `options.from`, set the constructor's `from: (t) => t.options.from` callback (the next example does this). Without that callback, `From:` falls back to per-letter `sendMail({ from })` or `options.mailOptions.from` on the transport itself.
 
 ```js
 // transports.js
 import nodemailer from 'nodemailer';
-// Use DIRECT transport
-// and enable sending email from localhost
-// install "nodemailer-direct-transport" NPM package:
-import directTransport from 'nodemailer-direct-transport';
-
-const transports = [];
-const directTransportOpts = {
-  pool: false,
-  direct: true,
-  name: 'mail.example.com',
-  from: 'no-reply@example.com',
-};
-transports.push(nodemailer.createTransport(directTransport(directTransportOpts)));
-// IMPORTANT: Add `.options` to a newly created transport,
-// this is necessary to make sure options are available to MailTime package:
-transports[0].options = directTransportOpts;
-
-// Private SMTP
-transports.push(nodemailer.createTransport({
-  host: 'smtp.example.com',
-  from: 'no-reply@example.com',
-  auth: {
-    user: 'no-reply',
-    pass: 'xxx'
-  },
-}));
-
-// Google Apps SMTP
-transports.push(nodemailer.createTransport({
-  host: 'smtp.gmail.com',
-  from: 'no-reply@mail.example.com',
-  auth: {
-    user: 'no-reply@mail.example.com',
-    pass: 'xxx'
-  },
-}));
 
-// Mailing service (SparkPost as example)
-transports.push(nodemailer.createTransport({
-  host: 'smtp.sparkpostmail.com',
-  port: 587,
-  from: 'no-reply@mail2.example.com',
-  auth: {
-    user: 'SMTP_Injection',
-    pass: 'xxx'
-  },
-}));
-
-export { transports };
+export const transports = [
+  nodemailer.createTransport({
+    host: 'smtp.example.com',
+    from: 'no-reply@example.com',
+    auth: { user: 'no-reply', pass: process.env.SMTP_PASS },
+  }),
+];
 ```
 
-#### 3. Initiate `mail-time`
-
-Create new instance of *MailTime* in the *Server* mode, — it will be able to __send__ and __add__ emails to the queue.
-
-#### 3a. Initiate and connect to Redis
+### 3. Initialize MailTime with a preset
 
-Connecting to Redis before initiating `new MailTime` instance:
+Pick the preset that matches the email class. Supply your own `queue`, `transports`, `josk.adapter`, and `prefix`. **Setting `prefix` on the constructor propagates into the queue adapter and the JoSk adapter automatically** — no need to repeat it.
 
 ```js
-// mail-queue.js
-import { MailTime, RedisQueue } from 'mail-time';
+// mail-queue.js — transactional emails on Redis
+import { MailTime, RedisQueue, mailTimePreset } from 'mail-time';
 import { createClient } from 'redis';
 import { transports } from './transports.js';
 
-// Use REDIS_URL environment variable to store connection string to MongoDB
-// example: "REDIS_URL=redis://127.0.0.1:6379/myapp node mail-micro-service.js"
 const redisClient = await createClient({ url: process.env.REDIS_URL }).connect();
-const mailQueue = new MailTime({
+
+const mailQueue = new MailTime(mailTimePreset('transactional', {
+  type: 'server',
+  prefix: 'app',
+  queue: new RedisQueue({ client: redisClient }),
+  josk: { adapter: { type: 'redis', client: redisClient } },
   transports,
-  queue: new MongoQueue({
-    client: redisClient,
-  }),
-  josk: {
-    adapter: {
-      type: 'redis',
-      client: redisClient,
-    }
+  from: (t) => `"Awesome App" <${t.options.from}>`,
+  onSent(email, info) {
+    console.log('sent', email.uuid, info);
   },
-  template: MailTime.Template // Use default template
-  from(transport) {
-    // To pass spam-filters `from` field should be correctly set
-    // for each transport, check `transport` object for more options
-    return `"Awesome App" <${transport.options.from}>`;
+  onError(error, email, info) {
+    console.error('failed', email.uuid, error, info);
   },
-  onError(error, email, details) {
-    console.log(`Email "${email.mailOptions.subject}" wasn't sent to ${email.mailOptions.to}`, error, details);
-  },
-  onSent(email, details) {
-    console.log(`Email "${email.mailOptions.subject}" successfully sent to ${email.mailOptions.to}`, details);
-  },
-});
+}));
 
+await mailQueue.ready();
 export { mailQueue };
 ```
 
-#### 3b. Initiate and connect to MongoDB
+Switching stores is one import change. The same pattern works with `MongoQueue({ db })` + `{ type: 'mongo', db }`, or `PostgresQueue({ client: pgPool })` + `{ type: 'postgres', client: pgPool }`.
 
-Connecting to MongoDB before initiating `new MailTime` instance:
+### 4. Send and cancel
 
 ```js
-// mail-queue.js
-import { MailTime, MongoQueue } from 'mail-time';
-import { MongoClient } from 'mongodb';
-import { transports } from './transports.js';
+import { mailQueue } from './mail-queue.js';
 
-// Use MONGO_URL environment variable to store connection string to MongoDB
-// example: "MONGO_URL=mongodb://127.0.0.1:27017/myapp node mail-micro-service.js"
-const mongodb = (await MongoClient.connect(process.env.MONGO_URL)).db('database');
-const mailQueue = new MailTime({
-  transports,
-  queue: new MongoQueue({
-    db: mongodb,
-  }),
-  josk: {
-    adapter: {
-      type: 'mongo',
-      db: mongodb,
-    }
-  },
-  template: MailTime.Template // Use default template
-  from(transport) {
-    // To pass spam-filters `from` field should be correctly set
-    // for each transport, check `transport` object for more options
-    return `"Awesome App" <${transport.options.from}>`;
-  },
-  onError(error, email, details) {
-    console.log(`Email "${email.mailOptions.subject}" wasn't sent to ${email.mailOptions.to}`, error, details);
-  },
-  onSent(email, details) {
-    console.log(`Email "${email.mailOptions.subject}" successfully sent to ${email.mailOptions.to}`, details);
-  },
+const uuid = await mailQueue.sendMail({
+  to: 'user@example.com',
+  subject: 'You\'ve got an email!',
+  text: 'Plain text body',
+  html: '<h1>HTML</h1><p>Styled body</p>',
 });
 
-export { mailQueue };
+// later — cancel before sendAt:
+await mailQueue.cancelMail(uuid); // true | false
 ```
 
-#### 3c. Optionally create *Client* type of *MailTime*
+`sendMail` returns a stable `uuid` you can store for cancellation. Pass any [nodemailer message option](https://nodemailer.com/message/) — `to`, `subject`, `text`, `html`, `attachments`, `cc`, `bcc`, custom headers, etc.
 
-Only __one__ `MailTime` *Server* instance required to send email. In the other parts of an app (like UI units or in sub-apps) use `mail-time` in the *Client* mode to __add__ emails to queue
+### 5. Client-only mode
+
+App servers that only enqueue need no `transports`, no `josk` — just the queue. Use the **same `prefix`** as the server that drains the class.
 
 ```js
-// mail-queue.js
 import { MailTime, RedisQueue } from 'mail-time';
 import { createClient } from 'redis';
 
-const mailQueue = new MailTime({
+const redisClient = await createClient({ url: process.env.REDIS_URL }).connect();
+
+export const mailQueue = new MailTime({
   type: 'client',
-  queue: new RedisQueue({
-    client: await createClient({ url: 'redis://url' }).connect()
-  }),
+  prefix: 'app',
+  queue: new RedisQueue({ client: redisClient }),
 });
-
-export { mailQueue };
 ```
 
-#### 4. Send email
-
-Import created `mailQueue` where needed and call `.sendMail()` method. See [NodeMailer's message configuration documentation](https://nodemailer.com/message/) for details
+### 6. Shutdown
 
 ```js
-import { mailQueue } from './mail-queue.js';
-
-await mailQueue.sendMail({
-  to: 'user@gmail.com',
-  subject: 'You\'ve got an email!',
-  text: 'Plain text message',
-  html: '<h1>HTML</h1><p>Styled message</p>'
+process.on('SIGTERM', async () => {
+  await mailQueue.destroy({ drain: true }); // stop scheduler, then wait for in-flight SMTPs
 });
 ```
 
-### Using MongoDB for queue and scheduler
+Or explicitly: `mailQueue.destroy(); await mailQueue.drain();`
 
-*MailTime* uses separate storage for Queue management and Scheduler. In the example below MongoDB is used for both
+`destroy()` is idempotent and stops the scheduler. Always call it from tests; pair with `drain()` when iterate-driven sends ran.
 
-```js
-import { MailTime, MongoQueue } from 'mail-time';
-import { MongoClient } from 'mongodb';
-import { transports } from './transports.js';
+## Storage layouts
 
-const db = (await MongoClient.connect('mongodb://url')).db('database');
-const mailQueue = new MailTime({
-  queue: new MongoQueue({
-    db: db,
-  }),
-  josk: {
-    adapter: {
-      type: 'mongo',
-      db: db,
-    }
-  },
-  transports,
-  from(transport) {
-    // To pass spam-filters `from` field should be correctly set
-    // for each transport, check `transport` object for more options
-    return `"Awesome App" <${transport.options.from}>`;
-  }
-});
-```
+Queue storage and scheduler storage can be the same store or different ones. Use this matrix:
 
-### Using MongoDB for queue and Redis for scheduler
+| Queue    | Scheduler (`josk`) | Best for                                     |
+| -------- | ------------------ | -------------------------------------------- |
+| Postgres | Postgres           | Multi-DC, mixed clocks, strict exactly-once. |
+| Redis    | Redis              | High-throughput single-region.               |
+| Mongo    | Mongo              | Apps already on Mongo (especially Meteor).   |
+| Mongo    | Redis              | Durable letter storage + sub-second polling. |
+| Redis    | Mongo              | Hot Redis letters + Mongo for scheduler.     |
 
-*MailTime* uses separate storage for Queue management and Scheduler. In the example below MongoDB is used for queue and Redis is used for scheduler
+For split-store setups pass a different client to each:
 
 ```js
-import { MailTime, MongoQueue } from 'mail-time';
-import { MongoClient } from 'mongodb';
-import { createClient } from 'redis';
-import { transports } from './transports.js';
-
 const mailQueue = new MailTime({
-  queue: new MongoQueue({
-    db: (await MongoClient.connect('mongodb://url')).db('database'),
-  }),
+  prefix: 'app',
+  queue:  new MongoQueue({ db }),
+  transports,
   josk: {
-    adapter: {
-      type: 'redis',
-      client: await createClient({ url: 'redis://url' }).connect(),
-    }
+    adapter: { type: 'redis', client: redisClient },
   },
-  transports,
-  from(transport) {
-    return `"Awesome App" <${transport.options.from}>`;
-  }
+  /* ... */
 });
 ```
 
-### Using Redis for queue and MongoDB for scheduler
+## Settings presets
 
-*MailTime* uses separate storage for Queue management and Scheduler. In the example below Redis is used for queue and MongoDB is used for scheduler
+Each email class wants a different policy — OTP must reach the inbox in seconds, a newsletter wants emails folded together, marketing tolerates retries spread over hours. `mailTimePreset(name, overrides)` applies a vetted shape in one line; you layer your own `queue` / `transports` / `josk.adapter` / `prefix` on top.
 
 ```js
-import { MailTime, RedisQueue } from 'mail-time';
-import { MongoClient } from 'mongodb';
-import { createClient } from 'redis';
-import { transports } from './transports.js';
+import { MailTime, RedisQueue, mailTimePreset } from 'mail-time';
 
-const mailQueue = new MailTime({
-  queue: new RedisQueue({
-    client: await createClient({ url: 'redis://url' }).connect(),
-  }),
-  josk: {
-    adapter: {
-      type: 'mongo',
-      db: (await MongoClient.connect('mongodb://url')).db('database'),
-    }
-  },
-  transports,
-  from(transport) {
-    return `"Awesome App" <${transport.options.from}>`;
-  }
-});
+const mailTime = new MailTime(mailTimePreset('otp', {
+  prefix: 'otp',
+  queue: new RedisQueue({ client: redisClient }),
+  transports: [otpTransport],
+  josk: { adapter: { type: 'redis', client: redisClient } },
+}));
 ```
 
-### Using Redis for queue and scheduler
+| Preset          | Shape                                                                                                                                              | Best for                                                                                |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `transactional` | `retries: 30`, `retryDelay: 10s`, `concatEmails: false`, `concurrency: 1`, `josk.zombieTime: 120s`                                                 | Receipts, password resets, account changes, welcome emails.                             |
+| `otp`           | `retries: 5`, `retryDelay: 2s`, snappy `revolvingInterval: 1024` + jitter `256/1024`, `concurrency: 4`, `sendingTimeout: 60s`                      | Sign-in codes, 2FA, verification codes — stale OTPs aren't worth resending forever.     |
+| `newsletter`    | `concatEmails: true` with a 5-minute fold window, `concatSubject: 'Your updates'`, `retries: 5`, `retryDelay: 60s`, `concurrency: 2`, `sendingTimeout: 10min`, `josk.zombieTime: 5min` | Scheduled digests, weekly summaries, "what's new" emails.                               |
+| `marketing`     | `retries: 10`, `retryDelay: 30s`, `concatEmails: false`, `concurrency: 5`, `josk.zombieTime: 3min`                                                 | Promotional / campaign blasts where each letter is unique.                              |
+| `notifications` | `concatEmails: true` with a 60-second fold window, `concatSubject: 'New activity'`, `retries: 8`, `retryDelay: 30s`, `concurrency: 3`, `josk.zombieTime: 3min` | App / social activity (likes, mentions, follows) where bursts collapse into one letter. |
+| `alerts`        | `retries: 20`, `retryDelay: 5s`, snappy `revolvingInterval: 1024` + jitter `256/1024`, `concurrency: 2`, `sendingTimeout: 60s`                     | Ops / admin alerts: monitoring, error reports, escalations.                             |
 
-*MailTime* uses separate storage for Queue management and Scheduler. In the example below Redis is used for both
+Presets are equally useful on `type: 'client'` instances — keys that don't apply to the client role are simply ignored.
 
-```js
-import { MailTime, RedisQueue } from 'mail-time';
-import { MongoClient } from 'mongodb';
-import { createClient } from 'redis';
-import { transports } from './transports.js';
+## Multiple instances (recommended)
 
-const redisClient = await createClient({ url: 'redis://url' }).connect();
-const mailQueue = new MailTime({
-  queue: new RedisQueue({
-    client: redisClient,
-  }),
-  josk: {
-    adapter: {
-      type: 'redis',
-      client: redisClient,
-    }
-  },
-  transports,
-  from(transport) {
-    return `"Awesome App" <${transport.options.from}>`;
-  }
-});
-```
+**Run one `MailTime` per email class** when policies differ (OTP vs marketing vs receipts). Each class gets its own `MailTime` options and, when policies differ, its own `prefix`. Combine with [presets](#settings-presets) to keep the boilerplate to a single line per class.
 
-### Two `MailTime` instances usage example
+- **Same `prefix`** for every `client` and `server` that share one logical queue.
+- **Different `prefix`** per class so namespaces don't collide.
+- **Never** reuse `prefix` across two instances with different `concatEmails`, `retryDelay`, or other mail policy.
 
-Create two `MailTime` instances with different settings. One for urgent (*e.g. "transactional" emails*), and another one for other types of emails (*e.g. "marketing" emails*)
+Full example wiring three classes (OTP / transactional / marketing) on one Redis connection, plus app-pod `client` setup, lives in [docs/multi-instance.md](https://github.com/veliovgroup/mail-time/blob/master/docs/multi-instance.md).
 
-```js
-import { MailTime, RedisQueue } from 'mail-time';
-import { createClient } from 'redis';
-import { transports } from './transports.js';
-const redisClient = await createClient({ url: 'redis://url' }).connect();
+## Dedicated mail host
 
-// CREATE mailQueue FOR NON-URGENT EMAILS WHICH IS OKAY TO CONCATENATE
-const mailQueue = new MailTime({
-  queue: new RedisQueue({
-    client: redisClient,
-  }),
-  transports,
-  strategy: 'backup',
-  failsToNext: 1,
-  concatEmails: true,
-  josk: {
-    adapter: {
-      type: 'redis',
-      client: redisClient
-    },
-    zombieTime: 120000
-  }
-});
+On a **single mail VM** (good rDNS / PTR, fixed SMTP credentials), run **2–8 `server` processes** (~one per CPU core) — typically **one process per email class**. Same `prefix` cluster-wide = one JoSk lease tick at a time, so extra pods on the same `prefix` buy **failover/HA**, not throughput.
 
-// CREATE mailInstantQueue FOR TRANSACTIONAL EMAILS AND ALERTS
-const mailInstantQueue = new MailTime({
-  queue: new RedisQueue({
-    client: redisClient,
-    prefix: 'instant'
-  }),
-  transports,
-  prefix: 'instant',
-  retryDelay: 2000,
-  strategy: 'backup',
-  failsToNext: 1,
-  concatEmails: false,
-  josk: {
-    adapter: {
-      type: 'redis',
-      client: redisClient
-    },
-    zombieTime: 20000
-  }
-});
+Full systemd unit + worker layout: [docs/dedicated-mail-host.md](https://github.com/veliovgroup/mail-time/blob/master/docs/dedicated-mail-host.md).
 
-await mailQueue.sendMail({
-  to: 'user@gmail.com',
-  subject: 'You\'ve got an email!',
-  text: 'Plain text message',
-  html: '<h1>HTML</h1><p>Styled message</p>'
-});
+## Tuning
 
-await mailInstantQueue.sendMail({
-  to: 'user@gmail.com',
-  subject: 'Sign in request',
-  text: 'Your OTP login code: xxxx:',
-  html: '<h1>Code:</h1><code>XXXX</code>'
-});
-```
+Defaults fit moderate traffic in a single region. Reach for a [preset](#settings-presets) first; tune individual knobs only when the preset doesn't cover your case. Full guide: [docs/tuning.md](https://github.com/veliovgroup/mail-time/blob/master/docs/tuning.md).
 
-### Passing variables to the template
+### Option reference (when to touch)
 
-All options passed to the `.sendMail()` method are available inside `text`, `html`, and global templates
+| Option                                         | Default          | Change when                                                                                                                        |
+| ---------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                                         | `'batch'`        | `'one'` to claim a single row per tick (fairness over throughput across cluster nodes)                                             |
+| `concurrency`                                  | `1`              | Raise to send N emails in parallel per instance. Bounded by your SMTP / API rate limits. The CAS on `isSending` keeps it safe.     |
+| `sendingTimeout`                               | `300000` (5 min) | Stale-lock recovery window. Must exceed worst-case SMTP roundtrip; lower it only when you're confident sends never take that long. |
+| `revolvingInterval`                            | `1536` ms        | Lower → faster pickup; higher → less scheduler I/O                                                                                 |
+| `josk.minRevolvingDelay` / `maxRevolvingDelay` | `512` / `2048`   | Lower both → snappier polls, more storage load                                                                                     |
+| `josk.zombieTime`                              | `60000`          | **Never below 60s.** Iterate releases the JoSk lease as soon as scanning ends — only a stalled storage scan can blow this.         |
+| `josk.concurrency`                             | `Infinity`       | Set `1` if scheduler ticks overlap while `iterate` still runs                                                                      |
+| `josk.execute`                                 | `'batch'`        | Usually leave default; MailTime only registers one JoSk task per instance                                                          |
+| `josk.lockOwnerId`                             | random           | Set in production for observability                                                                                                |
+| `retries` / `retryDelay`                       | `59` / `60s`     | `retries` is *after* the first attempt; default `59` means 60 total attempts. Per email class — transactional shorter, marketing longer. |
+| `concatEmails` / `concatDelay`                 | `false` / `60s`  | On for notification batching; off for OTP and receipts                                                                             |
+| `prefix`                                       | `''`             | **Same** on all `client` + `server` for one queue; **different** only per email class / shard                                      |
 
-```js
-const templates = {
-  global: '<html xmlns="http://www.w3.org/1999/xhtml"><head><title>{{subject}}</title></head><body>{{{html}}}<footer>Message sent to @{{username}} user ({{to}})</footer></body></html>',
-  signInCode: {
-    text: 'Hello @{{username}}! Here\'s your login code: {{code}}',
-    html: `<h1>Sign-in request</h1><p>Hello @{{username}}! <p>Copy your login code below:</p> <pre><code>{{code}}</code></pre>`
-  }
-};
+For deeper JoSk semantics (lease lifecycle, scheduler adapters, recurring tasks), install the JoSk skill: **`npx skills add veliovgroup/josk`**.
 
-const mailQueue = new MailTime({
-  queue: new RedisQueue({ /* ... */ }),
-  template: templates.global
-});
+## Templates
 
-await mailQueue.sendMail({
-  to: 'user@gmail.com',
-  subject: 'Sign-in request',
-  username: 'johndoe',
-  code: 'XXXXX-YY',
-  text: templates.signInCode.text,
-  html: templates.signInCode.html
-});
-```
+Two Mustache-like placeholder forms:
 
-## API
+- `{{key}}` — string interpolation, strips HTML from the value (safe for plain text).
+- `{{{key}}}` — raw HTML interpolation.
 
-All available constructor options and `.sendMail()` method API overview
-
-### `new MailTime(opts)` constructor
-
-- `opts` {*object*} - Configuration object
-- `opts.type` {*string*} - [Optional] `client` or `server`, default - `server`
-- `opts.queue` {*RedisQueue*|*MongoQueue*|*CustomQueue*} - Queue storage driver instance
-- `opts.transports` {*[object]*} - [*Required for "server"*] An array of `nodemailer`'s transports, returned from `nodemailer.createTransport({})`. Required for `{type: 'server'}`
-- `opts.josk` {*object*} - [*Required for "server"*] [`JoSk` package](https://github.com/veliovgroup/josk#api) options
-- `opts.josk.adapter` {*object*|*RedisAdapter*|*MongoAdapter*|*CustomAdapter*} - Config object or *Adapter* instance
-- `opts.josk.adapter.type` {*string*} - One of `mongo` *or* `redis`; Pass `josk.adapter.type` to avoid burden of creating *Adapter* instance manually
-- `opts.josk.adapter.client` {*RedisClient*} - *RedisClient* instance
-- `opts.josk.adapter.db` {*Db*} - Mongo's *Db* instance
-- `opts.josk[option]` {*mix*} - Any other options passed to [`JoSk` instance](https://github.com/veliovgroup/josk#api)
-- `opts.from` {*function*} - [Optional] A function which returns *string* of `from` field, format: `"MyApp" <user@example.com>`
-- `opts.strategy` {*string*} - [Optional] `backup` or `balancer`, default - `backup`. If set to `backup`, first transport will be used unless failed to send `failsToNext` times. If set to `balancer` - transports will be used equally in round robin chain
-- `opts.failsToNext` {*number*} - [Optional] After how many failed "send attempts" switch to the next transport, applied only for `backup` strategy, default - `4`
-- `opts.prefix` {*string*} - [Optional] Use unique prefixes to create multiple `MailTime` instances within the same application
-- `opts.retries` {*number*} - [Optional] How many times resend failed emails, default - `60`
-- `opts.retryDelay` {*number*} - [Optional] Interval in *milliseconds* between send re-tries, default - `60000`
-- `opts.keepHistory` {*boolean*} - [Optional] By default sent emails not stored in the database. Set `{ keepHistory: true }` to keep queue task as it is in the database, default - `false`
-- `opts.concatEmails` {*boolean*} - [Optional] Concatenate email by `to` field (*e.g. to the same addressee*), default - `false`
-- `opts.concatSubject` {*string*} - [Optional] Email subject used in concatenated email, default - `Multiple notifications`
-- `opts.concatDelimiter` {*string*} - [Optional] HTML or plain string delimiter used between concatenated email, default - `<hr>`
-- `opts.concatDelay` {*number*} - [Optional] Time in *milliseconds* while emails are waiting to be concatenated, default - `60000`
-- `opts.revolvingInterval` {*number*} - [Optional] Interval in *milliseconds* in between queue checks, default - `256`
-- `opts.template` {*string*} - [Optional] Mustache-like template, default - `{{{html}}}`, all options passed to `sendMail` is available in Template, like `to`, `subject`, `text`, `html` or any other custom option. Use `{{opt}}` for string placeholders and `{{{opt}}}` for html placeholders
-- `opts.onError(error, email, details)` {*function*} - [Optional] called when email has failed to get sent and exhausted all send attempts (`opts.retries`), called with 3 arguments:
-  - `error` {*Error*|*object*} - Error object
-  - `email` {*object*} - email's object
-  - `details` {*object*} - *not always present*, details from SMTP protocol
-- `opts.onSent(email, details)` {*function*} - [Optional] called when email was successfully handed over to receiving/recipient's SMTP server, called with 2 arguments:
-  - `email` {*object*} - email's object
-  - `details` {*object*} - *not always present*, details from SMTP server/protocol
+Every `sendMail` option is available inside `text`, `html`, and the wrapping template:
 
 ```js
-import { MailTime, MongoQueue, RedisQueue } from 'mail-time';
-import nodemailer from 'nodemailer';
-import { createClient } from 'redis';
-
-const redisClient = await createClient({ url: 'redis://url' }).connect();
+const layouts = {
+  envelope: `<html><body>{{{html}}}<footer>Sent to @{{username}} ({{to}})</footer></body></html>`,
+  otp: {
+    text: 'Hello @{{username}}! Your code: {{code}}',
+    html: '<h1>Sign-in</h1><p>Hello <b>@{{username}}</b></p><pre><code>{{code}}</code></pre>',
+  },
+};
 
 const mailQueue = new MailTime({
-  type: 'server',
-  strategy: 'backup',
-  prefix: 'appMailQueue',
-  transports: [nodemailer.createTransport({/* ... */})],
-  failsToNext: 4,
-  retries: 60,
-  retryDelay: 60000,
-  keepHistory: false,
-  concatEmails: false,
-  concatDelay: 60000,
-  concatDelimiter: '<hr>',
-  concatSubject: 'Multiple notifications',
-  revolvingInterval: 256,
-  template: '{{{html}}}',
-  queue: new RedisQueue({
-    client: redisClient,
-    prefix: 'appMailQueue',
-  }),
-  josk: {
-    adapter: {
-      type: 'redis',
-      client: redisClient,
-    }
-  },
-  from(transport) {
-    // To pass spam-filters `from` field should be correctly set
-    // for each transport, check `transport` object for more options
-    return `"App Name" <${transport.options.from}>`;
-  },
-  onError(error, email, details) {
-    console.log(`Email "${email.mailOptions.subject}" wasn't sent to ${email.mailOptions.to}`, error, details);
-  },
-  onSent(email, details) {
-    console.log(`Email "${email.mailOptions.subject}" successfully sent to ${email.mailOptions.to}`, details);
-  },
+  /* ... */
+  template: layouts.envelope,
 });
 
 await mailQueue.sendMail({
-  to: 'johndoe@example.com',
-  subject: 'Email subject',
-  text: 'You have got email!',
-  html: '<p>You have got email!</p>',
-});
-```
-
-### `new RedisQueue(opts)` constructor
-
-*Create Redis Queue instance.* Use for `opts.queue` when creating *MailTime* instance
-
-- `opts` {*object*} - Configuration object
-- `opts.client` {*RedisClient*} - Required, Redis'es `RedisClient` instance, like one returned from `await redis.createClient().connect()` method
-- `opts.prefix` {*string*} - Optional prefix for scope isolation; use when creating multiple `MailTime` instances within the single application
-
-```js
-import { MailTime, RedisQueue } from 'mail-time';
-import { createClient } from 'redis';
-
-new RedisQueue({
-  client: await createClient({ url: 'redis://url' }).connect(),
-  prefix: 'appMailQueue',
+  to: 'user@example.com',
+  subject: 'Sign-in code',
+  username: 'mike',
+  code: 'A1B2-C3D4',
+  text: layouts.otp.text,
+  html: layouts.otp.html,
 });
 ```
 
-### `new MongoQueue(opts)` constructor
-
-*Create MongoDB Queue instance.* Use for `opts.queue` when creating *MailTime* instance
-
-- `opts` {*object*} - Configuration object
-- `opts.db` {*Db*} - Required, Mongo's `Db` instance, like one returned from `MongoClient#db()`
-- `opts.prefix` {*string*} - Optional prefix for scope isolation; use when creating multiple `MailTime` instances within the single application
-
-```js
-import { MailTime, MongoQueue } from 'mail-time';
-import { MongoClient } from 'mongodb';
-
-new MongoQueue({
-  db: (await MongoClient.connect('mongodb://url')).db('database'),
-  prefix: 'appMailQueue',
-});
-```
-
-### `sendMail(opts)`
-
-*Add email to the queue.* Returns `Promise<string>` unique email's `uuid`
-
-- `opts` {*object*} - Configuration object
-- `opts.sendAt` {*number*} - When email should be sent, default - `Date.now()`
-- `opts.template` {*string*} - Email specific template, this will override default template passed to `MailTime` constructor
-- `opts.concatSubject` {*string*} - Email specific concatenation subject, this will override default concatenation subject passed to `MailTime` constructor
-- `opts[key]` {*mix*} - Other custom and NodeMailer specific options, like `text`, `html` and `to`, [learn more here](https://nodemailer.com/message/). __Note:__ if [`attachments`](https://nodemailer.com/message/attachments/) are used via `path` — file must exists on all micro-services servers
-
-### `cancelMail(uuid)`
-
-*Remove email from queue.* Returns `Promise<boolean>` — `true` if cancelled or `false` if not found, was sent, or was cancelled previously. Throws *Error*
+`MailTime.Template` is a bundled responsive HTML envelope you can use as the default — set it on the constructor or per-letter via `opts.template`.
 
-- `uuid` {*string*|*promise*} — email's `uuid` returned from `.sendEmail()` method
+## API
 
-```js
-import { mailQueue } from './mail-queue.js';
+### `new MailTime(opts)`
+
+| Option                        | Type                                                | Default                    | Notes                                                                                                                                                                                       |
+| ----------------------------- | --------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `queue`                       | `MongoQueue \| RedisQueue \| PostgresQueue \| CustomQueue` | —                    | **Required.** Storage adapter for letters. Custom adapters: see [docs/queue-api.md](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md).                                                                                     |
+| `type`                        | `'server' \| 'client'`                              | `'server'`                 | `'client'` only enqueues — no `transports` / `josk` required.                                                                                                                               |
+| `transports`                  | `nodemailer.Transport[]`                            | —                          | **Required for `server`**. Non-empty.                                                                                                                                                       |
+| `josk`                        | `MailTimeJoSkOptions`                               | —                          | **Required for `server`**. See [JoSk options](#josk-options) below.                                                                                                                         |
+| `strategy`                    | `'backup' \| 'balancer'`                            | `'backup'`                 | Multi-SMTP rotation policy.                                                                                                                                                                 |
+| `failsToNext`                 | `number`                                            | `4`                        | (`backup`) failures-in-a-row before rotating.                                                                                                                                               |
+| `retries`                     | `number`                                            | `59`                       | Re-send attempts after first failure. Total attempts = `retries + 1` (defaults to 60). Legacy alias `maxTries` is honored when `retries` is absent: `new MailTime({ maxTries: N })` sets total attempts to `N`.                |
+| `retryDelay`                  | `number` (ms)                                       | `60000`                    | Wait between attempts.                                                                                                                                                                      |
+| `keepHistory`                 | `boolean`                                           | `false`                    | Keep sent/failed/cancelled rows.                                                                                                                                                            |
+| `concatEmails`                | `boolean \| { subject?: string }`                   | `false`                    | Fold same-`to` letters into one. Pass `{ subject: 'X' }` to set the folded-letter subject inline; the string supports the `{{count}}` placeholder and overrides `concatSubject`.            |
+| `concatSubject`               | `string`                                            | `'Multiple notifications'` | Subject when folded. Supports `{{count}}` for the folded letter count.                                                                                                                      |
+| `concatDelimiter`             | `string`                                            | `'<hr>'`                   | Separator between folded bodies.                                                                                                                                                            |
+| `concatDelay`                 | `number` (ms)                                       | `60000`                    | Fold window.                                                                                                                                                                                |
+| `revolvingInterval`           | `number` (ms)                                       | `1536`                     | Queue iteration interval.                                                                                                                                                                   |
+| `mode`                        | `'one' \| 'batch'`                                  | `'batch'`                  | `'batch'` claims every due row per tick; `'one'` claims a single row per tick.                                                                                                              |
+| `concurrency`                 | `number`                                            | `1`                        | Parallel SMTPs per instance. The CAS on `isSending` prevents duplicate delivery.                                                                                                            |
+| `sendingTimeout`              | `number` (ms)                                       | `300000`                   | Window after which a stuck `isSending=true` row becomes eligible again. Must exceed worst-case SMTP roundtrip.                                                                              |
+| `verifyTransports`            | `boolean`                                           | `true`                     | Probe each transport via `transport.verify()` once at `ready()`. Failing transports are marked unusable, surfaced through `onError(error, null, { transportIndex, phase: 'verify' })`, and skipped during rotation/fallback. Throws from `ready()` if **every** transport fails. Transports without a `verify()` method are treated as healthy. |
+| `template`                    | `string`                                            | `'{{{html}}}'`             | Default envelope.                                                                                                                                                                           |
+| `prefix`                      | `string`                                            | `''`                       | Queue namespace. **Same** on every `client` and `server` for one logical queue; **different** per email class. Inherited by the queue adapter; JoSk scheduler uses `mailTimeQueue<prefix>`. |
+| `from`                        | `string \| (transport) => string`                   | —                          | Strongly recommended for spam-passing `From:` formatting.                                                                                                                                   |
+| `debug`                       | `boolean`                                           | `false`                    | Verbose logs.                                                                                                                                                                               |
+| `onSent(email, info)`         | `function`                                          | —                          | Called once the task is fully delivered. `email.mailOptions[i].accepted` lists every address that got through (across all attempts).                                                        |
+| `onError(error, email, info)` | `function`                                          | —                          | Called once the retry budget is exhausted with at least one un-accepted recipient. `email.mailOptions[i].rejected` lists each un-delivered address with its last error. Also fires once per transport that fails `verify()` at startup with `email === null` and `info = { transportIndex, phase: 'verify' }`. |
+
+### JoSk options
+
+`opts.josk` is passed to the underlying [`JoSk`](https://github.com/veliovgroup/josk) constructor. Useful keys:
+
+| Key                       | Default           | Notes                                                                                                          |
+| ------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| `adapter`                 | —                 | Either a constructed adapter or a config object: `{ type: 'redis' \| 'mongo' \| 'postgres', client \| db, prefix?, resetOnInit?, useHashTags? }`. MailTime constructs the adapter from the config object. Set `useHashTags: true` on Redis/KeyDB Cluster. |
+| `minRevolvingDelay`       | `512`             | Lower bound of poll window.                                                                                    |
+| `maxRevolvingDelay`       | `2048`            | Upper bound.                                                                                                   |
+| `zombieTime`              | `60000`           | Re-claim if `queue.iterate()` runs longer than this. **Do not drop below 60s.**                                |
+| `execute`                 | `'batch'`         | JoSk scheduler batching; low impact for MailTime (one interval task per instance).                             |
+| `concurrency`             | `Infinity`        | Cap overlapping JoSk handler runs on **this** process (`1` if ticks pile up).                                  |
+| `autoClear`               | `false`           | Remove orphan tasks from storage.                                                                              |
+| `lockOwnerId`             | `josk-<uuid>`     | Stable owner id; recommended per worker.                                                                       |
+| `onError(title, details)` | (logs to console) | Wire to your logger.                                                                                           |
+| `onExecuted(uid, details)` | —                 | Optional hook after each successful JoSk tick (observability).                                                 |
+
+For deeper JoSk semantics, install the JoSk skill: **`npx skills add veliovgroup/josk`** (the same author).
+
+### Methods
+
+- `sendMail(opts)` → `Promise<string>` uuid. Throws on missing `to` or on missing both `text` and `html`. Pass any nodemailer message option plus `sendAt` (Date or ms timestamp), `template`, `concatSubject`.
+- `send(opts)` — alias of `sendMail`.
+- `cancelMail(uuidOrPromise)` → `Promise<boolean>`. Accepts the `uuid` or the `Promise<string>` from `sendMail`.
+- `cancel(uuid)` — alias of `cancelMail`.
+- `ping()` → `Promise<{status, code, statusCode, error?}>`. Pings scheduler then queue.
+- `ready()` → `Promise<MailTime>`. Awaits all startup work; rejects with `.cause` on storage failure.
+- `destroy(opts?)` → `boolean` or `Promise<boolean>` when `{ drain: true }`. Stops scheduler. Idempotent. Use `destroy({ drain: true })` or `await drain()` after `destroy()` for graceful shutdown.
+- `drain()` → `Promise<void>`. Resolves once every in-flight SMTP attempt finishes. Useful in tests and graceful-shutdown paths.
+
+### Queue constructors
+
+| Constructor                              | Required option                                      | Optional                                                                                                     |
+| ---------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `new RedisQueue({ client, prefix? })`    | connected `redis@^4/^5` client with `watch()` + `multi()` | `prefix` — inherited from `MailTime` when omitted. Redis Cluster prefixes must map to one hash slot.        |
+| `new MongoQueue({ db, prefix? })`        | `db` from `MongoClient#db()`                         | `prefix` — inherited from `MailTime` when omitted. Indexes auto-created on first `ready()`.                  |
+| `new PostgresQueue({ client, prefix? })` | `pg.Pool` (recommended) or `pg.Client`               | `prefix` — inherited from `MailTime` when omitted. `mail_time_queue` table auto-migrated on first `ready()`. |
+
+For custom adapters see [docs/queue-api.md](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md).
+
+### Module functions
+
+- `mailTimePreset(name, overrides?)` → fresh MailTime constructor config. Deep-clones the named [preset](#settings-presets) and deep-merges your overrides (scalars win, nested `josk` composes). Throws on unknown `name` or non-object `overrides`.
+- `presets` — read-only `{ [name]: partialConfig }` map backing `mailTimePreset`.
+- `presetNames` — read-only array of preset names.
+
+### Static
+
+- `MailTime.Template` — get/set the default HTML envelope template.
+
+## Migration from 3.x
+
+Full v4 highlights, adapter changes, and type exports live in [docs/migration-v3-v4.md](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v3-v4.md). Quick checklist:
+
+1. **Node ≥ 20.9.0**, Bun ≥ 1.1.0. Bump your runtime first.
+2. **Swap adapter imports** to the new `MongoQueue` / `RedisQueue` / `PostgresQueue` constructors.
+3. **Pass `josk`** — it's now required for `type: 'server'`.
+4. **`josk.zombieTime` default raised to `60000` ms** (was `32786`). Set it explicitly if you relied on the old value.
+5. **Custom queue adapters** — `update`'s claim guard now triggers on `{ isSending: true, sendingAt, tries }` (was `{ isSent: true, tries }`) and must include the stale-lock-recovery clause `(isSending === false OR sendingAt <= now - sendingTimeout)`. The iterate path must call `await mailTimeInstance.___dispatch(row)` instead of `___send` and honor `opts.limit` / `opts.sendingTimeout`. See [docs/queue-api.md](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md) and [`adapters/blank-example.js`](https://github.com/veliovgroup/mail-time/blob/master/adapters/blank-example.js).
+6. **Default behavior unchanged** — `concurrency: 1` keeps the post-upgrade send rate identical to v3. Opt into parallel sends by raising `concurrency`.
+
+New v4 surface to opt into: [`mailTimePreset`](#settings-presets), `concurrency`, `mode`, `sendingTimeout`, `drain()`, per-recipient retries, and the [AI agent skills](#ai-agent-skills) bundle.
 
-const uuid = await mailQueue.sendMail({
-  to: 'johndoe@example.com',
-  subject: 'Email subject',
-  text: 'You have got email!',
-  html: '<p>You have got email!</p>',
-});
+## Testing
 
-await mailQueue.cancelMail(uuid);
+```sh
+npm install
+# DEFAULT RUN — needs Redis + Mongo + Postgres up locally
+REDIS_URL="redis://127.0.0.1:6379" \
+MONGO_URL="mongodb://127.0.0.1:27017/mail-time-test" \
+PG_URL="postgres://127.0.0.1:5432/postgres" \
+  npm test
+
+# Single suite
+npm run test:redis
+npm run test:mongo
+npm run test:postgres
+
+# Bun-native test runner (only Jest-shaped tests)
+bun test ./test/jest
 ```
 
-### `static MailTime.Template`
-
-Simple and bulletproof HTML template, see [its source](https://github.com/veliovgroup/mail-time/blob/master/template.html). Usage example:
-
-```js
-import { MailTime, MongoQueue, RedisQueue } from 'mail-time';
-
-// Make it default
-const mailQueue = new MailTime({
-  /* .. */
-  template: MailTime.Template
-});
-
-// For single letter
-mailQueue.sendMail({
-  /* .. */
-  template: MailTime.Template
-});
-```
+`npm test` runs Jest unit tests, then Mocha integration tests, then TypeScript declaration tests. Jest coverage threshold is **85%** across statements, branches, functions, and lines. GitHub Actions runs the matrix against `redis@^4` and `redis@^5`.
 
-### Template Example
+## Bun
 
-Pass custom template via `template` property to `.sendMail()` method
+MailTime ships pure ESM with a generated CJS bundle. Both runtimes (Bun ≥ 1.1.0, Node ≥ 20.9.0) load it directly:
 
 ```js
-mailQueue.sendMail({
-  to: 'user@gmail.com',
-  userName: 'Mike',
-  subject: 'Sign up confirmation',
-  text: 'Hello {{userName}}, \r\n Thank you for registration \r\n Your login: {{to}}',
-  html: '<div style="text-align: center"><h1>Hello {{userName}}</h1><p><ul><li>Thank you for registration</li><li>Your login: {{to}}</li></ul></p></div>',
-  template: '<body>{{{html}}}</body>'
-});
+import { MailTime } from 'mail-time'; // works in both
 ```
 
-## Testing
+Mixed clusters (some Node, some Bun) share one schedule under the same `prefix` — the lease lives in storage, runtime-agnostic.
 
-1. Clone this package
-2. Start local or obtain URLs for remote MongoDB and Redis servers
-3. In Terminal (*Console*) go to directory where package was cloned
-4. Then run:
+## License
 
-```shell
-# Before running tests make sure NODE_ENV === development
-# Install NPM dependencies
-npm install --save-dev
-
-# DEFAULT RUN
-REDIS_URL="redis://127.0.0.1:6379" MONGO_URL="mongodb://127.0.0.1:27017/npm-mail-time-test-001" npm test
-
-# OPTIONALLY RUN WITH CUSTOM DOMAIN
-EMAIL_DOMAIN="your-domain.com" REDIS_URL="redis://127.0.0.1:6379" MONGO_URL="mongodb://127.0.0.1:27017/npm-mail-time-test-001" npm test
-
-# IF SOME TESTS ARE FAILING: ENABLE DEBUG
-DEBUG="true" REDIS_URL="redis://127.0.0.1:6379" MONGO_URL="mongodb://127.0.0.1:27017/npm-mail-time-test-001" npm test
-
-# Be patient, tests are taking around 8 mins
-```
+[BSD-3-Clause](LICENSE).
 
-## Support this project:
+## Support this project
 
-- Upload and share files using [☄️ meteor-files.com](https://meteor-files.com/?ref=github-mail-time-repo-footer) — Continue interrupted file uploads without losing any progress. There is nothing that will stop Meteor from delivering your file to the desired destination
-- Use [▲ ostr.io](https://ostr.io?ref=github-mail-time-repo-footer) for [Server Monitoring](https://snmp-monitoring.com), [Web Analytics](https://ostr.io/info/web-analytics?ref=github-mail-time-repo-footer), [WebSec](https://domain-protection.info), [Web-CRON](https://web-cron.info) and [SEO Pre-rendering](https://prerendering.com) of a website
-- Star on [GitHub](https://github.com/veliovgroup/mail-time)
-- Star on [NPM](https://www.npmjs.com/package/mail-time)
-- Star on [Atmosphere](https://atmospherejs.com/ostrio/mailer)
-- [Sponsor maintainer via GitHub](https://github.com/sponsors/dr-dimitru) — support open source with one-time contribution or on a regular basis
-- [Sponsor veliovgroup via GitHub](https://github.com/sponsors/veliovgroup) — support company behind this package
-- [Support via PayPal](https://paypal.me/veliovgroup) — support our open source contributions
+- Star on [GitHub](https://github.com/veliovgroup/mail-time) and [NPM](https://www.npmjs.com/package/mail-time).
+- [Sponsor maintainer on GitHub](https://github.com/sponsors/dr-dimitru).
+- [Sponsor veliovgroup on GitHub](https://github.com/sponsors/veliovgroup).
+- [PayPal](https://paypal.me/veliovgroup).
+- Try [☄️ meteor-files.com](https://meteor-files.com/?ref=github-mail-time-repo-footer).
+- Try [▲ ostr.io](https://ostr.io?ref=github-mail-time-repo-footer) for server monitoring, web analytics, web-CRON, and SEO pre-rendering.